diff --git a/CMakeLists.txt b/CMakeLists.txt index 0926e3544b..d5436bffb3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -63,37 +63,37 @@ mark_as_advanced(CLEAR # Specify the VERSION and SOVERSION for shared libraries -set(arkodelib_VERSION "4.0.0-dev.2") +set(arkodelib_VERSION "4.0.0") set(arkodelib_SOVERSION "4") -set(cvodelib_VERSION "5.0.0-dev.2") +set(cvodelib_VERSION "5.0.0") set(cvodelib_SOVERSION "5") -set(cvodeslib_VERSION "5.0.0-dev.2") +set(cvodeslib_VERSION "5.0.0") set(cvodeslib_SOVERSION "5") -set(idalib_VERSION "5.0.0-dev.2") +set(idalib_VERSION "5.0.0") set(idalib_SOVERSION "5") -set(idaslib_VERSION "4.0.0-dev.2") +set(idaslib_VERSION "4.0.0") set(idaslib_SOVERSION "4") -set(kinsollib_VERSION "5.0.0-dev.2") +set(kinsollib_VERSION "5.0.0") set(kinsollib_SOVERSION "5") set(cpodeslib_VERSION "0.0.0") set(cpodeslib_SOVERSION "0") -set(nveclib_VERSION "5.0.0-dev.2") +set(nveclib_VERSION "5.0.0") set(nveclib_SOVERSION "5") -set(sunmatrixlib_VERSION "3.0.0-dev.2") +set(sunmatrixlib_VERSION "3.0.0") set(sunmatrixlib_SOVERSION "3") -set(sunlinsollib_VERSION "3.0.0-dev.2") +set(sunlinsollib_VERSION "3.0.0") set(sunlinsollib_SOVERSION "3") -set(sunnonlinsollib_VERSION "2.0.0-dev.2") +set(sunnonlinsollib_VERSION "2.0.0") set(sunnonlinsollib_SOVERSION "2") # Specify the location of additional CMAKE modules diff --git a/README.md b/README.md index d379e1b073..7f770d1922 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # SUNDIALS: SUite of Nonlinear and DIfferential/ALgebraic equation Solvers # -### Version 5.0.0-dev.2 (Sep 2019) ### +### Version 5.0.0 (Oct 2019) ### **Center for Applied Scientific Computing, Lawrence Livermore National Laboratory** diff --git a/doc/arkode/ARKode.tex b/doc/arkode/ARKode.tex index b3960980bd..2f3ab21bb1 100644 --- a/doc/arkode/ARKode.tex +++ b/doc/arkode/ARKode.tex @@ -55,8 +55,8 @@ \clearpage } -\title{User Documentation for ARKode v4.0.0-dev.2\\ - (SUNDIALS v5.0.0-dev.2)} +\title{User Documentation for ARKode v4.0.0\\ + (SUNDIALS v5.0.0)} \author{ Daniel R. Reynolds$^1$, David J. Gardner$^2$, \\ Alan C. Hindmarsh$^2$, Carol S. Woodward$^2$ \\ @@ -234,11 +234,11 @@ \chapter{Introduction} \(\mathbb{R}^N\), and the right-hand side function is partitioned into up to two components: \begin{itemize} -\item {} +\item {} \(f^E(t,y)\) contains the ``nonstiff'' time scale components to be integrated explicitly, and -\item {} +\item {} \(f^I(t,y)\) contains the ``stiff'' time scale components to be integrated implicitly. @@ -302,81 +302,159 @@ \section{Changes from previous versions} \subsection{Changes in v4.0.0} \label{Introduction:changes-in-v4-0-0} -The return type of the SUNLinearSolver API function -{\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolLastFlag]{\emph{\code{SUNLinSolLastFlag()}}}} has changed from \code{long int} to \code{sunindextype} -to be consistent with the type used to store row indices in dense and -banded linear solver modules. +\textbf{Build system changes} -Added Fortran 2003 interfaces to the \code{NVECTOR\_MANYVECTOR}, -\code{NVECTOR\_MPIMANYVECTOR} and \code{NVECTOR\_MPIPLUSX}. +Increased the minimum required CMake version to 3.5 for most SUNDIALS +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. -Added three new utility N\_Vector functions, \code{FN\_VGetVecAtIndexVectorArray}, -\code{FN\_VSetVecAtIndexVectorArray}, and \code{FN\_VNewVectorArray}, that are for working -with N\_Vector arrays when using the Fortran 2003 interfaces. - -Added a new \code{SUNNonlinearSolver} implementation, \code{SUNNonlinsol\_PetscSNES}, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSetConvTestFn]{\emph{\code{SUNNonlinSolSetConvTestFn()}}}} function in the -SUNNonlinearSolver API has been updated to take a \code{void*} data pointer as -input. The supplied data pointer will be passed to the nonlinear solver -convergence test function on each call. - -The definitions of \code{SUNNonlinSolLSetupFn()} and -\code{SUNNonlinSolLSolveFn()} in the SUNNonlinearSolver API have been updated -to remove unused input parameters. +The CMake option \code{BLAS\_ENABLE} and the variable \code{BLAS\_LIBRARIES} have been +removed to simplify builds as SUNDIALS packages do not use BLAS directly. For +third party libraries that require linking to BLAS, the path to the BLAS +library should be included in the \code{\_LIBRARIES} variable for the third party +library e.g., \code{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. -Support for optional inequality constraints on individual components of the -solution vector has been added the ARKode ERKStep and ARKStep modules. See -the descriptions of {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetConstraints]{\emph{\code{ERKStepSetConstraints()}}}} and -{\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetConstraints]{\emph{\code{ARKStepSetConstraints()}}}} for more details. Note that enabling -constraint handling requires the NVECTOR operations {\hyperref[nvectors/NVector_Operations:c.N_VMinQuotient]{\emph{\code{N\_VMinQuotient()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VConstrMask]{\emph{\code{N\_VConstrMask()}}}}, and {\hyperref[nvectors/NVector_Operations:c.N_VCompare]{\emph{\code{N\_VCompare()}}}} that were not previously -required by ARKode. +Fixed a bug in the build system that prevented the PThreads NVECTOR module from +being built. -Fixed a bug that would result in a ``too much accuracy requested'' error when -using fixed time step sizes with explicit methods in some cases. +\textbf{NVECTOR module changes} + +Two new functions were added to aid in creating custom NVECTOR objects. The +constructor {\hyperref[nvectors/NVector_Description:c.N_VNewEmpty]{\emph{\code{N\_VNewEmpty()}}}} allocates an ``empty'' generic NVECTOR with +the object's content pointer and the function pointers in the operations +structure initialized to \code{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the NVECTOR API by ensuring only required operations need to be set. +Additionally, the function {\hyperref[nvectors/NVector_Description:c.N_VCopyOps]{\emph{\code{N\_VCopyOps()}}}} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the NVECTOR API by ensuring all operations +are copied when cloning objects. + +Two new NVECTOR implementations, NVECTOR\_MANYVECTOR and +NVECTOR\_MPIMANYVECTOR, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and SUNDIALS +examples. +One new required vector operation and ten new optional vector operations have +been added to the NVECTOR API. The new required operation, {\hyperref[nvectors/NVector_Operations:c.N_VGetLength]{\emph{\code{N\_VGetLength()}}}}, +returns the global length of an \code{N\_Vector}. The optional operations have +been added to support the new NVECTOR\_MPIMANYVECTOR implementation. The +operation {\hyperref[nvectors/NVector_Operations:c.N_VGetCommunicator]{\emph{\code{N\_VGetCommunicator()}}}} must be implemented by subvectors that are +combined to create an NVECTOR\_MPIMANYVECTOR, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are +{\hyperref[nvectors/NVector_Operations:c.N_VDotProdLocal]{\emph{\code{N\_VDotProdLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VMaxNormLocal]{\emph{\code{N\_VMaxNormLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VMinLocal]{\emph{\code{N\_VMinLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VL1NormLocal]{\emph{\code{N\_VL1NormLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumLocal]{\emph{\code{N\_VWSqrSumLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumMaskLocal]{\emph{\code{N\_VWSqrSumMaskLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VInvTestLocal]{\emph{\code{N\_VInvTestLocal()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VConstrMaskLocal]{\emph{\code{N\_VConstrMaskLocal()}}}}, and +{\hyperref[nvectors/NVector_Operations:c.N_VMinQuotientLocal]{\emph{\code{N\_VMinQuotientLocal()}}}}. +If an NVECTOR implementation defines any of the local operations as +\code{NULL}, then the NVECTOR\_MPIMANYVECTOR will call standard NVECTOR +operations to complete the computation. + +An additional NVECTOR implementation, NVECTOR\_MPIPLUSX, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\emph{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and SUNDIALS examples. + +The \code{*\_MPICuda} and \code{*\_MPIRaja} functions have been removed from the +NVECTOR\_CUDA and NVECTOR\_RAJA implementations respectively. Accordingly, the +\code{nvector\_mpicuda.h}, \code{nvector\_mpiraja.h}, \code{libsundials\_nvecmpicuda.lib}, +and \code{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should +use the NVECTOR\_MPIPLUSX module coupled in conjunction with the NVECTOR\_CUDA +or NVECTOR\_RAJA modules to replace the functionality. The necessary changes are +minimal and should require few code modifications. See the programs in +\code{examples/ida/mpicuda} and \code{examples/ida/mpiraja} for examples of how to +use the NVECTOR\_MPIPLUSX module with the NVECTOR\_CUDA and NVECTOR\_RAJA modules +respectively. -\subsection{Changes in v4.0.0-dev.2} -\label{Introduction:changes-in-v4-0-0-dev-2} -Added a new optional operation to the SUNLINEARSOLVER API, \code{SUNLinSolGetID}, -that returns a \code{SUNLinearSolver\_ID} for identifying the linear solver module. +Fixed a memory leak in the NVECTOR\_PETSC module clone function. -Made performance improvements to the CUDA NVECTOR. Users who utilize a non --default stream should no longer see default stream synchronizations after -memory transfers. +Made performance improvements to the NVECTOR\_CUDA module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. -Added a new constructor to the CUDA NVECTOR that allows a user to provide +Added a new constructor to the NVECTOR\_CUDA module that allows a user to provide custom allocate and free functions for the vector data array and internal reduction buffer. -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. +Added new Fortran 2003 interfaces for most NVECTOR modules. See the +{\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} section for more details. + +Added three new NVECTOR utility functions, +\code{N\_VGetVecAtIndexVectorArray()} +\code{N\_VSetVecAtIndexVectorArray()}, and +\code{N\_VNewVectorArray()}, +for working with \code{N\_Vector} arrays when using the Fortran 2003 interfaces. + +\textbf{SUNMatrix module changes} + +Two new functions were added to aid in creating custom SUNMATRIX objects. The +constructor {\hyperref[sunmatrix/SUNMatrix_Description:c.SUNMatNewEmpty]{\emph{\code{SUNMatNewEmpty()}}}} allocates an ``empty'' generic SUNMATRIX with +the object's content pointer and the function pointers in the operations +structure initialized to \code{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the SUNMATRIX API by ensuring only required operations need to be set. +Additionally, the function {\hyperref[sunmatrix/SUNMatrix_Description:c.SUNMatCopyOps]{\emph{\code{SUNMatCopyOps()}}}} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the SUNMATRIX API by ensuring all operations are +copied when cloning objects. + +A new operation, {\hyperref[sunmatrix/SUNMatrix_Operations:c.SUNMatMatvecSetup]{\emph{\code{SUNMatMatvecSetup()}}}}, was added to the SUNMATRIX API. +Users who have implemented custom SUNMATRIX modules will need to at least +update their code to set the corresponding \code{ops} structure member, +\code{matvecsetup}, to \code{NULL}. + +A new operation, {\hyperref[sunmatrix/SUNMatrix_Operations:c.SUNMatMatvecSetup]{\emph{\code{SUNMatMatvecSetup()}}}}, was added to the SUNMATRIX API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for SUNMATRIX implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom SUNMATRIX modules will need to at +least update their code to set the corresponding \code{ops} structure member, +\code{matvecsetup}, to \code{NULL}. + +The generic SUNMATRIX API now defines error codes to be returned by +SUNMATRIX operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. + +A new SUNMATRIX (and SUNLINEARSOLVER) implementation was added to +facilitate the use of the SuperLU\_DIST library with SUNDIALS. + +Added new Fortran 2003 interfaces for most SUNMATRIX modules. See the +{\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} section for more details. + +\textbf{SUNLinearSolver module changes} + +A new function was added to aid in creating custom SUNLINEARSOLVER objects. +The constructor {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolNewEmpty]{\emph{\code{SUNLinSolNewEmpty()}}}} allocates an ``empty'' generic +SUNLINEARSOLVER with the object's content pointer and the function pointers +in the operations structure initialized to \code{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the SUNLINEARSOLVER API by ensuring only required +operations need to be set. -The CMake option \code{BLAS\_ENABLE} and the variable \code{BLAS\_LIBRARIES} have been -removed to simplify builds as SUNDIALS packages do not use BLAS directly. For -third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \code{\_LIBRARIES} variable for the third party -library e.g., \code{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. +The return type of the SUNLINEARSOLVER API function {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolLastFlag]{\emph{\code{SUNLinSolLastFlag()}}}} +has changed from \code{long int} to \code{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. -Fixed a bug in the ARKStep time-stepping module that would result in an infinite -loop if the nonlinear solver failed to converge more than the maximum allowed times -during a single step. - -Added two new `Get' functions to ARKStep, {\hyperref[sunnonlinsol/ARKode_Interface:c.ARKStepGetCurrentGamma]{\emph{\code{ARKStepGetCurrentGamma()}}}}, -and {\hyperref[sunnonlinsol/ARKode_Interface:c.ARKStepGetCurrentState]{\emph{\code{ARKStepGetCurrentState()}}}}, that may be useful to users who choose -to provide their own nonlinear solver implementation. +Added a new optional operation to the SUNLINEARSOLVER API, +{\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolGetID]{\emph{\code{SUNLinSolGetID()}}}}, that returns a \code{SUNLinearSolver\_ID} for identifying +the linear solver module. -Add two new `Set' functions to MRIStep, {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPreInnerFn]{\emph{\code{MRIStepSetPreInnerFn()}}}} and -{\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPostInnerFn]{\emph{\code{MRIStepSetPostInnerFn()}}}} for performing communication or memory -transfers needed before or after the inner integration. +The SUNLINEARSOLVER API has been updated to make the initialize and setup +functions optional. -The reinitialization functions {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepReInit]{\emph{\code{ERKStepReInit()}}}}, -{\hyperref[ARKStep_c_interface/User_callable:c.ARKStepReInit]{\emph{\code{ARKStepReInit()}}}}, and {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepReInit]{\emph{\code{MRIStepReInit()}}}} have been updated to -retain the minimum and maxiumum step size values from before reinitialization -rather than resetting them to the default values. +A new SUNLINEARSOLVER (and SUNMATRIX) implementation was added to +facilitate the use of the SuperLU\_DIST library with SUNDIALS. Added a new SUNLinearSolver implementation, \code{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently @@ -387,73 +465,65 @@ \subsection{Changes in v4.0.0-dev.2} {\hyperref[sunlinsol/SUNLinSol_KLU:c.SUNLinSol_KLUGetCommon]{\emph{\code{SUNLinSol\_KLUGetCommon()}}}}, to provide user access to the underlying KLU solver structures. +Added new Fortran 2003 interfaces for most SUNLINEARSOLVER modules. See the +{\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} section for more details. -\subsection{Changes in v4.0.0-dev.1} -\label{Introduction:changes-in-v4-0-0-dev-1} -Several new functions were added to aid in creating custom NVECTOR, SUNMATRIX, -SUNLINEARSOLVER, and SUNNONLINEARSOLVER objects. The constructors -{\hyperref[nvectors/NVector_Description:c.N_VNewEmpty]{\emph{\code{N\_VNewEmpty()}}}}, {\hyperref[sunmatrix/SUNMatrix_Description:c.SUNMatNewEmpty]{\emph{\code{SUNMatNewEmpty()}}}}, -{\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolNewEmpty]{\emph{\code{SUNLinSolNewEmpty()}}}}, and {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolNewEmpty]{\emph{\code{SUNNonlinSolNewEmpty()}}}} allocate -``empty'' generic NVECTOR, SUNMATRIX, SUNLINEARSOLVER, and SUNNONLINEARSOLVER -objects respectively with the object's content pointer and the function pointers -in the operations structure initialized to \code{NULL}. When used in the -constructor for custom objects these functions will ease the introduction of any -new optional operations to the NVECTOR, SUNMATRIX, SUNLINEARSOLVER, or -SUNNONLINEARSOLVER APIs by ensuring only required operations need to be -set. Additionally, the functions {\hyperref[nvectors/NVector_Description:c.N_VCopyOps]{\emph{\code{N\_VCopyOps()}}}} and -{\hyperref[sunmatrix/SUNMatrix_Description:c.SUNMatCopyOps]{\emph{\code{SUNMatCopyOps()}}}} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the NVECTOR or SUNMATRIX APIs by -ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. +\textbf{SUNNonlinearSolver module changes} -A new linear solver interface function {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsLinSysFn]{\emph{\code{ARKLsLinSysFn()}}}} was added as an -alternative method for evaluating the linear system \(A = M - \gamma J\). +A new function was added to aid in creating custom SUNNONLINEARSOLVER +objects. The constructor {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolNewEmpty]{\emph{\code{SUNNonlinSolNewEmpty()}}}} allocates an ``empty'' +generic SUNNONLINEARSOLVER with the object's content pointer and the function +pointers in the operations structure initialized to \code{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the SUNNONLINEARSOLVER API by ensuring only +required operations need to be set. -The ARKLS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \code{SUNLINEARSOLVER\_DIRECT}. +To facilitate the use of user supplied nonlinear solver convergence test +functions the {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSetConvTestFn]{\emph{\code{SUNNonlinSolSetConvTestFn()}}}} function in the +SUNNONLINEARSOLVER API has been updated to take a \code{void*} data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. -Fixed a bug in ARKStep where the mass matrix linear solver setup function was -not called in the Matrix-free case. +The inputs values passed to the first two inputs of the {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSolve]{\emph{\code{SUNNonlinSolSolve()}}}} +function in the SUNNONLINEARSOLVER have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolLSetupFn]{\emph{\code{SUNNonlinSolLSetupFn}}}} and {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolLSolveFn]{\emph{\code{SUNNonlinSolLSolveFn}}}} +in the SUNNONLINEARSOLVER API have been updated to remove unused input +parameters. -Fixed a minor bug in ARKStep where an incorrect flag is reported when an -error occurs in the mass matrix setup or Jacobian-vector product setup -functions. +Added a new \code{SUNNonlinearSolver} implementation, \code{SUNNonlinsol\_PetscSNES}, +which interfaces to the PETSc SNES nonlinear solver API. -Fixed a bug in the build system that prevented the PThreads NVECTOR module from -being built. +Added new Fortran 2003 interfaces for most SUNNONLINEARSOLVER modules. See the +{\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} section for more details. -Fixed a memory leak in the NVECTOR\_PETSC clone function. +\textbf{ARKode changes} -Fixed a memeory leak in FARKODE when not using the default nonlinear solver. +The MRIStep module has been updated to support explicit, implicit, or IMEX +methods as the fast integrator using the ARKStep module. As a result some +function signatures have been changed including {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepCreate]{\emph{\code{MRIStepCreate()}}}} which +now takes an ARKStep memory structure for the fast integration as an input. -Added two new embedded ARK methods of orders 4 and 5 to ARKode (from \phantomsection\label{Introduction:id7}{\hyperref[References:kc2019]{\emph{{[}KC2019{]}}}}). +Fixed a bug in the ARKStep time-stepping module that would result in an infinite +loop if the nonlinear solver failed to converge more than the maximum allowed times +during a single step. -The ManyVector NVECTOR module has been split into two versions: one -that requires MPI (MPIManyVector) and another that does not use MPI at -all (ManyVector). The associated example problems have been similarly -updated to reflect this new structure. +Fixed a bug that would result in a ``too much accuracy requested'' error when +using fixed time step sizes with explicit methods in some cases. -An additional NVECTOR implementation, NVECTOR\_MPIPLUSX, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and SUNDIALS -examples. +Fixed a bug in ARKStep where the mass matrix linear solver setup function was +not called in the Matrix-free case. -The *\_MPICuda and *\_MPIRaja functions were removed from the NVECTOR\_CUDA and -NVECTOR\_RAJA implementations respectively. Accordingly, the \code{nvector\_mpicuda.h}, -\code{nvector\_mpiraja.h}, \code{libsundials\_nvecmpicuda.lib}, and \code{libsundials\_nvecmpicudaraja.lib} -files have been removed. Users should use the NVECTOR\_MPIPLUSX module coupled with -the NVECTOR\_CUDA or NVECTOR\_RAJA to replace the functionality. The necessary changes -are minimal and should require few code modifications. +Fixed a minor bug in ARKStep where an incorrect flag is reported when an +error occurs in the mass matrix setup or Jacobian-vector product setup +functions. -A new Fortran 2003 interface to ARKode was added. This includes Fortran 2003 interfaces -to the ARKStep, ERKStep, and MRIStep time-stepping modules as well as all generic SUNDIALS -types (i.e. NVECTOR, SUNMATRIX, SUNLINEARSOLVER, SUNNONLINEARSOLVER), and many of the module -implementations. See Section {\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} for more details. +Fixed a memeory leak in FARKODE when not using the default nonlinear solver. + +The reinitialization functions {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepReInit]{\emph{\code{ERKStepReInit()}}}}, +{\hyperref[ARKStep_c_interface/User_callable:c.ARKStepReInit]{\emph{\code{ARKStepReInit()}}}}, and {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepReInit]{\emph{\code{MRIStepReInit()}}}} have been updated to +retain the minimum and maxiumum step size values from before reinitialization +rather than resetting them to the default values. Removed extraneous calls to {\hyperref[nvectors/NVector_Operations:c.N_VMin]{\emph{\code{N\_VMin()}}}} for simulations where the scalar valued absolute tolerance, or all entries of the @@ -461,54 +531,34 @@ \subsection{Changes in v4.0.0-dev.1} this scenario, ARKode will remove at least one global reduction per time step. +The ARKLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type \code{SUNLINEARSOLVER\_DIRECT}. -\subsection{Changes in v4.0.0-dev.0} -\label{Introduction:changes-in-v4-0-0-dev-0} -An additional NVECTOR implementation, NVECTOR\_MANYVECTOR, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see the -Section {\hyperref[nvectors/NVector_ManyVector:nvectors-manyvector]{\emph{\DUspan{}{The NVECTOR\_MANYVECTOR Module}}}} for more details). This -implementation is accompanied by additions to user documentation and -SUNDIALS examples. - -Eleven new optional vector operations have been added to the NVECTOR API to -support the new NVECTOR\_MANYVECTOR implementation (see the Chapter {\hyperref[nvectors/index:nvectors]{\emph{\DUspan{}{Vector Data Structures}}}} -for more details). Two of the operations, {\hyperref[nvectors/NVector_Operations:c.N_VGetCommunicator]{\emph{\code{N\_VGetCommunicator()}}}} and -{\hyperref[nvectors/NVector_Operations:c.N_VGetLength]{\emph{\code{N\_VGetLength()}}}}, must be implemented by subvectors that are combined to -create an NVECTOR\_MANYVECTOR, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are -{\hyperref[nvectors/NVector_Operations:c.N_VDotProdLocal]{\emph{\code{N\_VDotProdLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VMaxNormLocal]{\emph{\code{N\_VMaxNormLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VMinLocal]{\emph{\code{N\_VMinLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VL1NormLocal]{\emph{\code{N\_VL1NormLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumLocal]{\emph{\code{N\_VWSqrSumLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumMaskLocal]{\emph{\code{N\_VWSqrSumMaskLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VInvTestLocal]{\emph{\code{N\_VInvTestLocal()}}}}, -{\hyperref[nvectors/NVector_Operations:c.N_VConstrMaskLocal]{\emph{\code{N\_VConstrMaskLocal()}}}}, and -{\hyperref[nvectors/NVector_Operations:c.N_VMinQuotientLocal]{\emph{\code{N\_VMinQuotientLocal()}}}}. -If an NVECTOR implementation defines any of the local operations as \code{NULL}, -then the NVECTOR\_MANYVECTOR will call standard NVECTOR operations to complete -the computation. +A new linear solver interface function {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsLinSysFn]{\emph{\code{ARKLsLinSysFn()}}}} was added as an +alternative method for evaluating the linear system \(A = M - \gamma J\). + +Added two new embedded ARK methods of orders 4 and 5 to ARKode (from \phantomsection\label{Introduction:id7}{\hyperref[References:kc2019]{\emph{{[}KC2019{]}}}}). -A new SUNMatrix and SUNLinearSolver implementation was added to facilitate -the use of the SuperLU\_DIST library with SUNDIALS. +Support for optional inequality constraints on individual components of the +solution vector has been added the ARKode ERKStep and ARKStep modules. See +the descriptions of {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetConstraints]{\emph{\code{ERKStepSetConstraints()}}}} and +{\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetConstraints]{\emph{\code{ARKStepSetConstraints()}}}} for more details. Note that enabling +constraint handling requires the NVECTOR operations {\hyperref[nvectors/NVector_Operations:c.N_VMinQuotient]{\emph{\code{N\_VMinQuotient()}}}}, +{\hyperref[nvectors/NVector_Operations:c.N_VConstrMask]{\emph{\code{N\_VConstrMask()}}}}, and {\hyperref[nvectors/NVector_Operations:c.N_VCompare]{\emph{\code{N\_VCompare()}}}} that were not previously +required by ARKode. -A new operation, \code{SUNMatMatvecSetup}, was added to the SUNMatrix API. Users -who have implemented custom \code{SUNMatrix} modules will need to at least update -their code to set the corresponding ops structure member, \code{matvecsetup}, to \code{NULL}. +Added two new `Get' functions to ARKStep, {\hyperref[sunnonlinsol/ARKode_Interface:c.ARKStepGetCurrentGamma]{\emph{\code{ARKStepGetCurrentGamma()}}}}, +and {\hyperref[sunnonlinsol/ARKode_Interface:c.ARKStepGetCurrentState]{\emph{\code{ARKStepGetCurrentState()}}}}, that may be useful to users who choose +to provide their own nonlinear solver implementation. -The generic SUNMatrix API now defines error codes to be returned by SUNMatrix operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. +Add two new `Set' functions to MRIStep, {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPreInnerFn]{\emph{\code{MRIStepSetPreInnerFn()}}}} and +{\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPostInnerFn]{\emph{\code{MRIStepSetPostInnerFn()}}}} for performing communication or memory +transfers needed before or after the inner integration. -The MRIStep module has been updated to support explicit, implicit, or IMEX -methods as the fast integrator using the ARKStep module. As a result some -function signatures have been changed including {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepCreate]{\emph{\code{MRIStepCreate()}}}} which -now takes an ARKStep memory structure for the fast integration as an input. +A new Fortran 2003 interface to ARKode was added. This includes Fortran 2003 interfaces +to the ARKStep, ERKStep, and MRIStep time-stepping modules. See the +{\hyperref[ARKode_f_interface/index:fortraninterfaces]{\emph{\DUspan{}{Using ARKode for Fortran Applications}}}} section for more details. \subsection{Changes in v3.1.0} @@ -554,12 +604,12 @@ \subsection{Changes in v3.0.0} have been encapsulated inside the new \code{ARKStep} time-stepping module. Two new time-stepping modules have been added: \begin{itemize} -\item {} +\item {} The \code{ERKStep} module provides an optimized implementation for explicit Runge-Kutta methods with reduced storage and number of calls to the ODE right-hand side function. -\item {} +\item {} The \code{MRIStep} module implements two-rate explicit-explicit multirate infinitesimal step methods utilizing different step sizes for slow and fast processes in an additive splitting. @@ -582,10 +632,10 @@ \subsection{Changes in v3.0.0} Two changes were made in the initial step size algorithm: \begin{itemize} -\item {} +\item {} Fixed an efficiency bug where an extra call to the right hand side function was made. -\item {} +\item {} Changed the behavior of the algorithm if the max-iterations case is hit. Before the algorithm would exit with the step size calculated on the penultimate iteration. Now it will exit with the step size calculated @@ -672,28 +722,28 @@ \subsection{Changes in v3.0.0} Multiple changes to the CUDA NVECTOR were made: \begin{itemize} -\item {} +\item {} Changed the \code{N\_VMake\_Cuda} function to take a host data pointer and a device data pointer instead of an \code{N\_VectorContent\_Cuda} object. -\item {} +\item {} Changed \code{N\_VGetLength\_Cuda} to return the global vector length instead of the local vector length. -\item {} +\item {} Added \code{N\_VGetLocalLength\_Cuda} to return the local vector length. -\item {} +\item {} Added \code{N\_VGetMPIComm\_Cuda} to return the MPI communicator used. -\item {} +\item {} Removed the accessor functions in the namespace \code{suncudavec}. -\item {} +\item {} Added the ability to set the \code{cudaStream\_t} used for execution of the CUDA NVECTOR kernels. See the function \code{N\_VSetCudaStreams\_Cuda}. -\item {} +\item {} Added \code{N\_VNewManaged\_Cuda}, \code{N\_VMakeManaged\_Cuda}, and \code{N\_VIsManagedMemory\_Cuda} functions to accommodate using managed memory with the CUDA NVECTOR. @@ -701,17 +751,17 @@ \subsection{Changes in v3.0.0} Multiple changes to the RAJA NVECTOR were made: \begin{itemize} -\item {} +\item {} Changed \code{N\_VGetLength\_Raja} to return the global vector length instead of the local vector length. -\item {} +\item {} Added \code{N\_VGetLocalLength\_Raja} to return the local vector length. -\item {} +\item {} Added \code{N\_VGetMPIComm\_Raja} to return the MPI communicator used. -\item {} +\item {} Removed the accessor functions in the namespace \code{sunrajavec}. \end{itemize} @@ -747,31 +797,31 @@ \subsection{Changes in v2.2.0} Several changes were made to the build system: \begin{itemize} -\item {} +\item {} CMake 3.1.3 is now the minimum required CMake version. -\item {} +\item {} Deprecate the behavior of the \code{SUNDIALS\_INDEX\_TYPE} CMake option and added the \code{SUNDIALS\_INDEX\_SIZE} CMake option to select the \code{sunindextype} integer size. -\item {} +\item {} The native CMake FindMPI module is now used to locate an MPI installation. -\item {} +\item {} If MPI is enabled and MPI compiler wrappers are not set, the build system will check if \code{CMAKE\_\textless{}language\textgreater{}\_COMPILER} can compile MPI programs before trying to locate and use an MPI installation. -\item {} +\item {} The previous options for setting MPI compiler wrappers and the executable for running MPI programs have been have been depreated. The new options that align with those used in native CMake FindMPI module are \code{MPI\_C\_COMPILER}, \code{MPI\_CXX\_COMPILER}, \code{MPI\_Fortran\_COMPILER}, and \code{MPIEXEC\_EXECUTABLE}. -\item {} +\item {} When a Fortran name-mangling scheme is needed (e.g., \code{LAPACK\_ENABLE} is \code{ON}) the build system will infer the scheme from the Fortran compiler. If a Fortran compiler is not available or the inferred or default @@ -780,7 +830,7 @@ \subsection{Changes in v2.2.0} be used to manually set the name-mangling scheme and bypass trying to infer the scheme. -\item {} +\item {} Parts of the main CMakeLists.txt file were moved to new files in the \code{src} and \code{example} directories to make the CMake configuration file structure more modular. @@ -875,42 +925,42 @@ \subsection{Changes in v2.0.0} Specific changes include: \begin{itemize} -\item {} +\item {} Added generic SUNMATRIX module with three provided implementations: dense, banded and sparse. These replicate previous SUNDIALS Dls and Sls matrix structures in a single object-oriented API. -\item {} +\item {} Added example problems demonstrating use of generic SUNMATRIX modules. -\item {} +\item {} Added generic SUNLINEARSOLVER module with eleven provided implementations: dense, banded, LAPACK dense, LAPACK band, KLU, SuperLU\_MT, SPGMR, SPBCGS, SPTFQMR, SPFGMR, PCG. These replicate previous SUNDIALS generic linear solvers in a single object-oriented API. -\item {} +\item {} Added example problems demonstrating use of generic SUNLINEARSOLVER modules. -\item {} +\item {} Expanded package-provided direct linear solver (Dls) interfaces and scaled, preconditioned, iterative linear solver (Spils) interfaces to utilize generic SUNMATRIX and SUNLINEARSOLVER objects. -\item {} +\item {} Removed package-specific, linear solver-specific, solver modules (e.g. CVDENSE, KINBAND, IDAKLU, ARKSPGMR) since their functionality is entirely replicated by the generic Dls/Spils interfaces and SUNLINEARSOLVER/SUNMATRIX modules. The exception is CVDIAG, a diagonal approximate Jacobian solver available to CVODE and CVODES. -\item {} +\item {} Converted all SUNDIALS example problems to utilize new generic SUNMATRIX and SUNLINEARSOLVER objects, along with updated Dls and Spils linear solver interfaces. -\item {} +\item {} Added Spils interface routines to ARKode, CVODE, CVODES, IDA and IDAS to allow specification of a user-provided ``JTSetup'' routine. This change supports users who wish to set up data structures for @@ -984,94 +1034,94 @@ \subsection{Changes in v1.1.0} The bugfixes include: \begin{itemize} -\item {} +\item {} For each linear solver, the various solver performance counters are now initialized to 0 in both the solver specification function and in the solver's \code{linit} function. This ensures that these solver counters are initialized upon linear solver instantiation as well as at the beginning of the problem solution. -\item {} +\item {} The choice of the method vs embedding the Billington and TRBDF2 explicit Runge-Kutta methods were swapped, since in those the lower-order coefficients result in an A-stable method, while the higher-order coefficients do not. This change results in significantly improved robustness when using those methods. -\item {} +\item {} A bug was fixed for the situation where a user supplies a vector of absolute tolerances, and also uses the vector Resize() functionality. -\item {} +\item {} A bug was fixed wherein a user-supplied Butcher table without an embedding is supplied, and the user is running with either fixed time steps (or they do adaptivity manually); previously this had resulted in an error since the embedding order was below 1. -\item {} +\item {} Numerous aspects of the documentation were fixed and/or clarified. \end{itemize} The feature changes/enhancements include: \begin{itemize} -\item {} +\item {} Two additional NVECTOR implementations were added -- one for Hypre (parallel) ParVector vectors, and one for PETSc vectors. These additions are accompanied by additions to various interface functions and to user documentation. -\item {} +\item {} Each NVECTOR module now includes a function, \code{N\_VGetVectorID}, that returns the NVECTOR module name. -\item {} +\item {} A memory leak was fixed in the banded preconditioner and banded-block-diagonal preconditioner interfaces. In addition, updates were done to return integers from linear solver and preconditioner `free' routines. -\item {} +\item {} The Krylov linear solver Bi-CGstab was enhanced by removing a redundant dot product. Various additions and corrections were made to the interfaces to the sparse solvers KLU and SuperLU\_MT, including support for CSR format when using KLU. -\item {} +\item {} The ARKode implicit predictor algorithms were updated: methods 2 and 3 were improved slightly, a new predictor approach was added, and the default choice was modified. -\item {} +\item {} The underlying sparse matrix structure was enhanced to allow both CSR and CSC matrices, with CSR supported by the KLU linear solver interface. ARKode interfaces to the KLU solver from both C and Fortran were updated to enable selection of sparse matrix type, and a Fortran-90 CSR example program was added. -\item {} +\item {} The missing \code{ARKSpilsGetNumMtimesEvals()} function was added -- this had been included in the previous documentation but had not been implemented. -\item {} +\item {} The handling of integer codes for specifying built-in ARKode Butcher tables was enhanced. While a global numbering system is still used, methods now have \#defined names to simplify the user interface and to streamline incorporation of new Butcher tables into ARKode. -\item {} +\item {} The maximum number of Butcher table stages was increased from 8 to 15 to accommodate very high order methods, and an 8th-order adaptive ERK method was added. -\item {} +\item {} Support was added for the explicit and implicit methods in an additive Runge-Kutta method to utilize different stage times, solution and embedding coefficients, to support new SSP-ARK methods. -\item {} +\item {} The FARKODE interface was extended to include a routine to set scalar/array-valued residual tolerances, to support Fortran applications with non-identity mass-matrices. @@ -1089,16 +1139,16 @@ \section{Reading this User Guide} The structure of this document is as follows: \begin{itemize} -\item {} +\item {} In the next section we provide a thorough presentation of the underlying {\hyperref[Mathematics:mathematics]{\emph{\DUspan{}{mathematics}}}} used within the ARKode family of solvers. -\item {} +\item {} We follow this with an overview of how the source code for ARKode is {\hyperref[Organization:organization]{\emph{\DUspan{}{organized}}}}. -\item {} +\item {} The largest section follows, providing a full account of the ARKStep module user interface, including a description of all user-accessible functions and outlines for usage in serial and @@ -1106,11 +1156,11 @@ \section{Reading this User Guide} present a section on {\hyperref[ARKStep_c_interface/index:arkstep-cinterface]{\emph{\DUspan{}{using ARKStep for C and C++ applications}}}}, followed with a separate section on {\hyperref[ARKode_f_interface/FARKODE:fortraninterface]{\emph{\DUspan{}{using ARKode within Fortran applications}}}}. -\item {} +\item {} The much smaller section describing the ERKStep time-stepping module, {\hyperref[ERKStep_c_interface/index:erkstep-cinterface]{\emph{\DUspan{}{using ERKStep for C and C++ applications}}}}, follows. -\item {} +\item {} Subsequent sections discuss shared features between ARKode and the rest of the SUNDIALS library: {\hyperref[nvectors/index:nvectors]{\emph{\DUspan{}{vector data structures}}}}, @@ -1118,7 +1168,7 @@ \section{Reading this User Guide} {\hyperref[sunlinsol/index:sunlinsol]{\emph{\DUspan{}{linear solver data structures}}}}, and the {\hyperref[Install:installation]{\emph{\DUspan{}{installation procedure}}}}. -\item {} +\item {} The final sections catalog the full set of {\hyperref[Constants:constants]{\emph{\DUspan{}{ARKode constants}}}}, that are used for both input specifications and return codes, and the full set of {\hyperref[Butcher:butcher]{\emph{\DUspan{}{Butcher tables}}}} that are packaged with ARKode. @@ -1154,16 +1204,16 @@ \subsection{BSD 3-Clause License} Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: \begin{itemize} -\item {} +\item {} Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -\item {} +\item {} Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -\item {} +\item {} Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. @@ -1306,7 +1356,7 @@ \section{Adaptive single-step methods} ARKode's time stepping modules may be run in a variety of ``modes'': \begin{itemize} -\item {} +\item {} \textbf{NORMAL} -- The solver will take internal steps until it has just overtaken a user-specified output time, \(t_\text{out}\), in the direction of integration, i.e. \(t_{n-1} < t_\text{out} \le @@ -1316,21 +1366,21 @@ \section{Adaptive single-step methods} interpolation (using one of the dense output routines described in the section {\hyperref[Mathematics:mathematics-interpolation]{\emph{\DUspan{}{Interpolation}}}}). -\item {} +\item {} \textbf{ONE-STEP} -- The solver will only take a single internal step \(y_{n-1} \to y_{n}\) and then return control back to the calling program. If this step will overtake \(t_\text{out}\) then the solver will again return an interpolated result; otherwise it will return a copy of the internal solution \(y_{n}\). -\item {} +\item {} \textbf{NORMAL-TSTOP} -- The solver will take internal steps until the next step will overtake \(t_\text{out}\). It will then limit this next step so that \(t_n = t_{n-1} + h_n = t_\text{out}\), and once the step completes it will return a copy of the internal solution \(y_{n}\). -\item {} +\item {} \textbf{ONE-STEP-TSTOP} -- The solver will check whether the next step will overtake \(t_\text{out}\) -- if not then this mode is identical to ``one-step'' above; otherwise it will limit this next @@ -1370,22 +1420,22 @@ \section{Interpolation} \end{gather} we then construct the interpolants \(p_q(t)\) as follows: \begin{itemize} -\item {} +\item {} \(q=0\): constant interpolant \begin{gather} \begin{split}p_0(\tau) = \frac{y_{n-1} + y_{n}}{2}.\end{split}\notag \end{gather} -\item {} +\item {} \(q=1\): linear Lagrange interpolant \begin{gather} \begin{split}p_1(\tau) = -\tau\, y_{n-1} + (1+\tau)\, y_{n}.\end{split}\notag \end{gather} -\item {} +\item {} \(q=2\): quadratic Hermite interpolant \begin{gather} \begin{split}p_2(\tau) = \tau^2\,y_{n-1} + (1-\tau^2)\,y_{n} + h(\tau+\tau^2)\,f_{n}.\end{split}\notag \end{gather} -\item {} +\item {} \(q=3\): cubic Hermite interpolant \begin{gather} \begin{split}p_3(\tau) = (3\tau^2 + 2\tau^3)\,y_{n-1} + @@ -1409,11 +1459,11 @@ \section{ARKStep -- Additive Runge-Kutta methods} i.e. the right-hand side function is additively split into two components: \begin{itemize} -\item {} +\item {} \(f^E(t,y)\) contains the ``nonstiff'' components of the system. This will be integrated using an explicit method. -\item {} +\item {} \(f^I(t,y)\) contains the ``stiff'' components of the system. This will be integrated using an implicit method. @@ -1537,11 +1587,11 @@ \section{MRIStep -- Multirate infinitesimal step methods} i.e. the right-hand side function is additively split into two components: \begin{itemize} -\item {} +\item {} \(f^S(t,y)\) contains the ``slow'' components of the system. This will be integrated using a large time step \(h^S\). -\item {} +\item {} \(f^F(t,y)\) contains the ``fast'' components of the system. This will be integrated using a small time step \(h^F\). @@ -1554,29 +1604,29 @@ \section{MRIStep -- Multirate infinitesimal step methods} solving an auxiliary ODE with an inner (fast) Runge-Kutta method. This corresponds to the following algorithm for a single step: \begin{enumerate} -\item {} +\item {} Set \(z_1 = y_{n-1}\) -\item {} +\item {} For \(i = 2,\ldots,s+1\) \begin{enumerate} -\item {} +\item {} Let \(v(t^S_{n,i-1}) = z_{i-1}\) -\item {} +\item {} Compute \(r = \frac{1}{c^S_i - c^S_{i-1}} \sum_{j=1}^{i-1} (A^S_{i,j} - A^S_{i-1,j}) f^S(t^S_{n,j}, z_j)\) -\item {} +\item {} For \(\tau \in [t^S_{n,i-1}, t^S_{n,i}]\), solve \(\dot{v}(\tau) = f^F(\tau, v) + r\) -\item {} +\item {} Set \(z_i = v(t^S_{n,i})\), \end{enumerate} -\item {} +\item {} Set \(y_{n} = z_{s+1}\), \end{enumerate} @@ -1922,14 +1972,14 @@ \subsection{Fixed time stepping} problem-specific information. In this mode, all internal time step adaptivity is disabled: \begin{itemize} -\item {} +\item {} temporal error control is disabled, -\item {} +\item {} nonlinear or linear solver non-convergence will result in an error (instead of a step size adjustment), -\item {} +\item {} no check against an explicit stability condition is performed. \end{itemize} @@ -2065,39 +2115,39 @@ \subsection{Linear solver methods} iterative (Krylov) linear solvers. The methods offered through these modules are as follows: \begin{itemize} -\item {} +\item {} dense direct solvers, using either an internal SUNDIALS implementation or a BLAS/LAPACK implementation (serial version only), -\item {} +\item {} band direct solvers, using either an internal SUNDIALS implementation or a BLAS/LAPACK implementation (serial version only), -\item {} +\item {} sparse direct solvers, using either the KLU sparse matrix library \phantomsection\label{Mathematics:id18}{\hyperref[References:klu]{\emph{{[}KLU{]}}}}, or the OpenMP or PThreads-enabled SuperLU\_MT sparse matrix library \phantomsection\label{Mathematics:id19}{\hyperref[References:superlumt]{\emph{{[}SuperLUMT{]}}}} {[}Note that users will need to download and install the KLU or SuperLU\_MT packages independent of ARKode{]}, -\item {} +\item {} SPGMR, a scaled, preconditioned GMRES (Generalized Minimal Residual) solver, -\item {} +\item {} SPFGMR, a scaled, preconditioned FGMRES (Flexible Generalized Minimal Residual) solver, -\item {} +\item {} SPBCGS, a scaled, preconditioned Bi-CGStab (Bi-Conjugate Gradient Stable) solver, -\item {} +\item {} SPTFQMR, a scaled, preconditioned TFQMR (Transpose-free Quasi-Minimal Residual) solver, or -\item {} +\item {} PCG, a preconditioned CG (Conjugate Gradient method) solver for symmetric linear systems. @@ -2203,25 +2253,25 @@ \subsubsection{Updating the linear solver} these structures will be recomputed only in the following circumstances: \begin{itemize} -\item {} +\item {} when starting the problem, -\item {} +\item {} when more than 20 steps have been taken since the last update (this value may be modified by the user), -\item {} +\item {} when the value \(\tilde{\gamma}\) of \(\gamma\) at the last update satisfies \(\left|\gamma/\tilde{\gamma} - 1\right| > 0.2\) (this value may be modified by the user), -\item {} +\item {} when a non-fatal convergence failure just occurred, -\item {} +\item {} when an error test failure just occurred, or -\item {} +\item {} if the problem is linearly implicit and \(\gamma\) has changed by a factor larger than 100 times machine epsilon. @@ -2235,21 +2285,21 @@ \subsubsection{Updating the linear solver} decision is made to re-evaluate \(J\) (or instruct the user to update \(P\)) when: \begin{itemize} -\item {} +\item {} starting the problem, -\item {} +\item {} more than 50 steps have been taken since the last evaluation, -\item {} +\item {} a convergence failure occurred with an outdated matrix, and the value \(\tilde{\gamma}\) of \(\gamma\) at the last update satisfies \(\left|\gamma/\tilde{\gamma} - 1\right| > 0.2\), -\item {} +\item {} a convergence failure occurred that forced a step size reduction, or -\item {} +\item {} if the problem is linearly implicit and \(\gamma\) has changed by a factor larger than 100 times machine epsilon. @@ -2800,26 +2850,26 @@ \chapter{Code Organization} solver packages presently available, and the basic functionality of each: \begin{itemize} -\item {} +\item {} CVODE, a linear multistep solver for stiff and nonstiff ODE systems \(\dot{y} = f(t,y)\) based on Adams and BDF methods; -\item {} +\item {} CVODES, a linear multistep solver for stiff and nonstiff ODEs with sensitivity analysis capabilities; -\item {} +\item {} ARKode, a Runge-Kutta based solver for stiff, nonstiff, and mixed ODE systems; -\item {} +\item {} IDA, a linear multistep solver for differential-algebraic systems \(F(t,y,\dot{y}) = 0\) based on BDF methods; -\item {} +\item {} IDAS, a linear multistep solver for differential-algebraic systems with sensitivity analysis capabilities; -\item {} +\item {} KINSOL, a solver for nonlinear algebraic systems \(F(u) = 0\). \end{itemize} @@ -2918,16 +2968,16 @@ \section{ARKode organization} ARKode's linear solver interface consists of four primary phases, devoted to \begin{enumerate} -\item {} +\item {} memory allocation and initialization, -\item {} +\item {} setup of the matrix/preconditioner data involved, -\item {} +\item {} solution of the system, and -\item {} +\item {} freeing of memory. \end{enumerate} @@ -3015,10 +3065,10 @@ \section{Access to library and header files} appropriate locations for the library and header files required by ARKode. The relevant library files are \begin{itemize} -\item {} +\item {} \code{libdir/libsundials\_arkode.lib}, -\item {} +\item {} \code{libdir/libsundials\_nvec*.lib}, \end{itemize} @@ -3027,22 +3077,22 @@ \section{Access to library and header files} libraries and \code{.a} for static libraries. The relevant header files are located in the subdirectories \begin{itemize} -\item {} +\item {} \code{incdir/include/arkode} -\item {} +\item {} \code{incdir/include/sundials} -\item {} +\item {} \code{incdir/include/nvector} -\item {} +\item {} \code{incdir/include/sunmatrix} -\item {} +\item {} \code{incdir/include/sunlinsol} -\item {} +\item {} \code{incdir/include/sunnonlinsol} \end{itemize} @@ -3148,7 +3198,7 @@ \section{Header Files} files so that various macros and data types can be used. The header file that is always required is: \begin{itemize} -\item {} +\item {} \code{arkode/arkode\_arkstep.h}, the main header file for the ARKStep time-stepping module, which defines the several types and various constants, includes function prototypes, and includes the shared @@ -3190,65 +3240,65 @@ \section{Header Files} corresponding to the SUNDIALS-provided linear solver modules available for use with ARKode are: \begin{itemize} -\item {} +\item {} Direct linear solvers: \begin{itemize} -\item {} +\item {} \code{sunlinsol/sunlinsol\_dense.h}, which is used with the dense linear solver module, SUNLINSOL\_DENSE; -\item {} +\item {} \code{sunlinsol/sunlinsol\_band.h}, which is used with the banded linear solver module, SUNLINSOL\_BAND; -\item {} +\item {} \code{sunlinsol/sunlinsol\_lapackdense.h}, which is used with the LAPACK dense linear solver module, SUNLINSOL\_LAPACKDENSE; -\item {} +\item {} \code{sunlinsol/sunlinsol\_lapackband.h}, which is used with the LAPACK banded linear solver module, SUNLINSOL\_LAPACKBAND; -\item {} +\item {} \code{sunlinsol/sunlinsol\_klu.h}, which is used with the KLU sparse linear solver module, SUNLINSOL\_KLU; -\item {} +\item {} \code{sunlinsol/sunlinsol\_superlumt.h}, which is used with the SuperLU\_MT sparse linear solver module, SUNLINSOL\_SUPERLUMT; \end{itemize} -\item {} +\item {} Iterative linear solvers: \begin{itemize} -\item {} +\item {} \code{sunlinsol/sunlinsol\_spgmr.h}, which is used with the scaled, preconditioned GMRES Krylov linear solver module, SUNLINSOL\_SPGMR; -\item {} +\item {} \code{sunlinsol/sunlinsol\_spfgmr.h}, which is used with the scaled, preconditioned FGMRES Krylov linear solver module, SUNLINSOL\_SPFGMR; -\item {} +\item {} \code{sunlinsol/sunlinsol\_spbcgs.h}, which is used with the scaled, preconditioned Bi-CGStab Krylov linear solver module, SUNLINSOL\_SPBCGS; -\item {} +\item {} \code{sunlinsol/sunlinsol\_sptfqmr.h}, which is used with the scaled, preconditioned TFQMR Krylov linear solver module, SUNLINSOL\_SPTFQMR; -\item {} +\item {} \code{sunlinsol/sunlinsol\_pcg.h}, which is used with the scaled, preconditioned CG Krylov linear solver module, SUNLINSOL\_PCG; @@ -3296,14 +3346,14 @@ \section{A skeleton of the user's main program} the function to be called or macro to be referenced. \index{User main program}\begin{enumerate} -\item {} +\item {} Initialize parallel or multi-threaded environment, if appropriate. For example, call \code{MPI\_Init} to initialize MPI if used, or set \code{num\_threads}, the number of threads to use within the threaded vector functions, if used. -\item {} +\item {} Set problem dimensions, etc. This generally includes the problem size, \code{N}, and may include @@ -3314,7 +3364,7 @@ \section{A skeleton of the user's main program} \code{sunindextype}. \end{notice} -\item {} +\item {} Set vector of initial values To set the vector \code{y0} of initial values, use the appropriate @@ -3383,7 +3433,7 @@ \section{A skeleton of the user's main program} and device when instantiated. See the sections {\hyperref[nvectors/NVector_CUDA:nvectors-cuda]{\emph{\DUspan{}{The NVECTOR\_CUDA Module}}}} and {\hyperref[nvectors/NVector_RAJA:nvectors-raja]{\emph{\DUspan{}{The NVECTOR\_RAJA Module}}}} for details. -\item {} +\item {} Create ARKStep object Call \code{arkode\_mem = ARKStepCreate(...)} to create the ARKStep memory @@ -3391,7 +3441,7 @@ \section{A skeleton of the user's main program} this memory structure. See the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-initialization]{\emph{\DUspan{}{ARKStep initialization and deallocation functions}}}} for details. -\item {} +\item {} Specify integration tolerances Call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSStolerances]{\emph{\code{ARKStepSStolerances()}}}} or @@ -3410,7 +3460,7 @@ \section{A skeleton of the user's main program} {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResStolerance]{\emph{\code{ARKStepResStolerance()}}}}, {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResVtolerance]{\emph{\code{ARKStepResVtolerance()}}}}, or {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResFtolerance]{\emph{\code{ARKStepResFtolerance()}}}}. -\item {} +\item {} Create matrix object If a nonlinear solver requiring a linear solver will be used (e.g., @@ -3447,7 +3497,7 @@ \section{A skeleton of the user's main program} NOTE: The dense, banded, and sparse matrix objects are usable only in a serial or threaded environment. -\item {} +\item {} Create linear solver object If a nonlinear solver requiring a linear solver will be used (e.g., @@ -3467,7 +3517,7 @@ \section{A skeleton of the user's main program} options, as discussed in the sections {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-linearsolvers]{\emph{\DUspan{}{Linear solver interface functions}}}} and {\hyperref[sunlinsol/index:sunlinsol]{\emph{\DUspan{}{Description of the SUNLinearSolver module}}}}. -\item {} +\item {} Set linear solver optional inputs Call \code{*Set*} functions from the selected linear solver module @@ -3475,7 +3525,7 @@ \section{A skeleton of the user's main program} documentation for each SUNLINSOL module in the section {\hyperref[sunlinsol/index:sunlinsol]{\emph{\DUspan{}{Description of the SUNLinearSolver module}}}} for details. -\item {} +\item {} Attach linear solver module If a linear solver was created above for implicit stage solves, @@ -3497,14 +3547,14 @@ \section{A skeleton of the user's main program} \PYG{n}{ier} \PYG{o}{=} \PYG{n}{ARKStepSetMassLinearSolver}\PYG{p}{(}\PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Set optional inputs Call \code{ARKStepSet*} functions to change any optional inputs that control the behavior of ARKStep from their default values. See the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for details. -\item {} +\item {} Create nonlinear solver object If the problem involves an implicit component, and if a non-default @@ -3529,7 +3579,7 @@ \section{A skeleton of the user's main program} \PYG{n}{SUNNonlinearSolver} \PYG{n}{NLS} \PYG{o}{=} \PYG{n}{SUNNonlinSol\PYGZus{}FixedPoint}\PYG{p}{(}\PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Attach nonlinear solver module If a nonlinear solver object was created above, then it must be @@ -3540,7 +3590,7 @@ \section{A skeleton of the user's main program} \PYG{n}{ier} \PYG{o}{=} \PYG{n}{ARKStepSetNonlinearSolver}\PYG{p}{(}\PYG{p}{.}\PYG{p}{.}\PYG{p}{.}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Set nonlinear solver optional inputs Call the appropriate set functions for the selected nonlinear @@ -3550,7 +3600,7 @@ \section{A skeleton of the user's main program} overridden by ARKStep defaults. See the section {\hyperref[sunnonlinsol/index:sunnonlinsol]{\emph{\DUspan{}{Description of the SUNNonlinearSolver Module}}}} for more information on optional inputs. -\item {} +\item {} Specify rootfinding problem Optionally, call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepRootInit]{\emph{\code{ARKStepRootInit()}}}} to initialize a rootfinding @@ -3559,7 +3609,7 @@ \section{A skeleton of the user's main program} the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for relevant optional input calls. -\item {} +\item {} Advance solution in time For each point at which output is desired, call @@ -3573,13 +3623,13 @@ \section{A skeleton of the user's main program} \(y(t_\text{out})\). See the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-integration]{\emph{\DUspan{}{ARKStep solver function}}}} for details. -\item {} +\item {} Get optional outputs Call \code{ARKStepGet*} functions to obtain optional output. See the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}} for details. -\item {} +\item {} Deallocate memory for solution vector Upon completion of the integration, deallocate memory for the @@ -3589,20 +3639,20 @@ \section{A skeleton of the user's main program} \PYG{n}{N\PYGZus{}VDestroy}\PYG{p}{(}\PYG{n}{y}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Free solver memory Call \code{ARKStepFree(\&arkode\_mem)} to free the memory allocated for the ARKStep module (and any nonlinear solver module). -\item {} +\item {} Free linear solver and matrix memory Call {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolFree]{\emph{\code{SUNLinSolFree()}}}} and (possibly) {\hyperref[sunmatrix/SUNMatrix_Operations:c.SUNMatDestroy]{\emph{\code{SUNMatDestroy()}}}} to free any memory allocated for the linear solver and matrix objects created above. -\item {} +\item {} Finalize MPI, if used Call \code{MPI\_Finalize} to terminate MPI. @@ -3627,239 +3677,239 @@ \subsection{SUNDIALS linear solver interfaces and vector implementations that ca \label{ARKStep_c_interface/Skeleton:sundials-linear-solver-interfaces-and-vector-implementations-that-can-be-used-for-each}\label{ARKStep_c_interface/Skeleton:arkstep-cinterface-solver-vector} \begin{tabulary}{\linewidth}{|L|L|L|L|L|L|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Linear Solver Interface -} & \textsf{\relax +} & \textsf{\relax Serial -} & \textsf{\relax +} & \textsf{\relax Parallel (MPI) -} & \textsf{\relax +} & \textsf{\relax OpenMP -} & \textsf{\relax +} & \textsf{\relax pThreads -} & \textsf{\relax +} & \textsf{\relax \emph{hypre} Vec. -} & \textsf{\relax +} & \textsf{\relax PETSc Vec. -} & \textsf{\relax +} & \textsf{\relax CUDA -} & \textsf{\relax +} & \textsf{\relax RAJA -} & \textsf{\relax +} & \textsf{\relax User Suppl. }\\ \hline Dense - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline Band - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline LapackDense - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline LapackBand - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline KLU - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline SuperLU\_DIST - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & & & + & & & X \\ \hline SuperLU\_MT - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline SPGMR - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline SPFGMR - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline SPBCGS - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline SPTFQMR - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline PCG - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline User supplied - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline\end{tabulary} @@ -3894,20 +3944,20 @@ \subsection{ARKStep initialization and deallocation functions} solved using the ARKStep time-stepping module in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{fe} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the explicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\). -\item {} +\item {} \emph{fi} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the implicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). \end{itemize} @@ -3929,7 +3979,7 @@ \subsection{ARKStep initialization and deallocation functions} {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepCreate]{\emph{\code{ARKStepCreate()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} @@ -3981,28 +4031,28 @@ \subsection{ARKStep tolerance specification functions} This function specifies scalar relative and absolute tolerances. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{reltol} -- scalar relative tolerance. -\item {} +\item {} \emph{abstol} -- scalar absolute tolerance. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -4020,29 +4070,29 @@ \subsection{ARKStep tolerance specification functions} each vector component). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{reltol} -- scalar relative tolerance. -\item {} +\item {} \emph{abstol} -- vector containing the absolute tolerances for each solution component. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -4054,28 +4104,28 @@ \subsection{ARKStep tolerance specification functions} \index{ARKStepWFtolerances (C function)} \begin{fulllineitems} -\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepWFtolerances}\pysiglinewithargsret{int \bfcode{ARKStepWFtolerances}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{ARKEwtFn}}}\emph{ efun}}{} +\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepWFtolerances}\pysiglinewithargsret{int \bfcode{ARKStepWFtolerances}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{ARKEwtFn}}}\emph{ efun}}{} This function specifies a user-supplied function \emph{efun} to compute the error weight vector \code{ewt}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} -\emph{efun} -- the name of the function (of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}}) +\item {} +\emph{efun} -- the name of the function (of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}}) that implements the error weight vector computation. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module \end{itemize} @@ -4127,25 +4177,25 @@ \subsection{ARKStep tolerance specification functions} This function specifies a scalar absolute residual tolerance. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rabstol} -- scalar absolute residual tolerance. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -4161,26 +4211,26 @@ \subsection{ARKStep tolerance specification functions} This function specifies a vector of absolute residual tolerances. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rabstol} -- vector containing the absolute residual tolerances for each solution component. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -4197,23 +4247,23 @@ \subsection{ARKStep tolerance specification functions} the residual weight vector \code{rwt}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rfun} -- the name of the function (of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKRwtFn]{\emph{\code{ARKRwtFn()}}}}) that implements the residual weight vector computation. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ARKStep memory was not allocated by the time-stepping module \end{itemize} @@ -4230,7 +4280,7 @@ \subsubsection{General advice on the choice of tolerances} \code{reltol}, \code{abstol}, and \code{rabstol} are a concern. The following pieces of advice are relevant. \begin{enumerate} -\item {} +\item {} The scalar relative tolerance \code{reltol} is to be set to control relative errors. So a value of \(10^{-4}\) means that errors are controlled to .01\%. We do not recommend using \code{reltol} larger @@ -4238,7 +4288,7 @@ \subsubsection{General advice on the choice of tolerances} small that it is comparable to the unit roundoff of the machine arithmetic (generally around \(10^{-15}\) for double-precision). -\item {} +\item {} The absolute tolerances \code{abstol} (whether scalar or vector) need to be set to control absolute errors when any components of the solution vector \(y\) may be so small that pure relative error @@ -4258,7 +4308,7 @@ \subsubsection{General advice on the choice of tolerances} problem-dependent. The user or modeler hopefully has some idea as to what those noise levels are. -\item {} +\item {} The residual absolute tolerances \code{rabstol} (whether scalar or vector) follow a similar explanation as for \code{abstol}, except that these should be set to the noise level of the equation @@ -4267,7 +4317,7 @@ \subsubsection{General advice on the choice of tolerances} unset, which will default to the already-supplied \code{abstol} values. -\item {} +\item {} Finally, it is important to pick all the tolerance values conservatively, because they control the error committed on each individual step. The final (global) errors are an accumulation of @@ -4292,14 +4342,14 @@ \subsubsection{Advice on controlling nonphysical negative values} that violates a constraint may cause a simulation to halt. For both of these scenarios the following pieces of advice are relevant. \begin{enumerate} -\item {} +\item {} The best way to control the size of unwanted negative computed values is with tighter absolute tolerances. Again this requires some knowledge of the noise level of these components, which may or may not be different for different components. Some experimentation may be needed. -\item {} +\item {} If output plots or tables are being generated, and it is important to avoid having negative numbers appear there (for the sake of avoiding a long explanation of them, if nothing else), then @@ -4309,7 +4359,7 @@ \subsubsection{Advice on controlling nonphysical negative values} magnitude comparable to \code{abstol} or less, is equivalent to zero as far as the computation is concerned. -\item {} +\item {} The user's right-hand side routines \(f^E\) and \(f^I\) should never change a negative value in the solution vector \(y\) to a non-negative value in attempt to ``fix'' this problem, @@ -4320,7 +4370,7 @@ \subsubsection{Advice on controlling nonphysical negative values} temporary variable (not in the input \(y\) vector) for the purposes of computing \(f^E(t, y)\) or \(f^I(t, y)\). -\item {} +\item {} Positivity and non-negativity constraints on components can be enforced by use of the recoverable error return feature in the user-supplied right-hand side functions, \(f^E\) and @@ -4426,29 +4476,29 @@ \subsection{Linear solver interface functions} applicable). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{LS} -- the \code{SUNLinearSolver} object to use. -\item {} +\item {} \emph{J} -- the template Jacobian \code{SUNMatrix} object to use (or \code{NULL} if not applicable). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if ARKLS is incompatible with the provided \emph{LS} or \emph{J} input objects, or the current \code{N\_Vector} module. @@ -4528,7 +4578,7 @@ \subsection{Mass matrix solver specification functions} Note: if the user program includes linear solvers for \emph{both} the Newton and mass matrix systems, these must have the same type: \begin{itemize} -\item {} +\item {} If both are matrix-based, then they must utilize the same \code{SUNMatrix} type, since these will be added when forming the Newton system matrices \({\mathcal A}\). In this case, both the @@ -4536,7 +4586,7 @@ \subsection{Mass matrix solver specification functions} \code{SUNLinearSolver} object, although different solver objects (e.g. with different solver parameters) are also allowed. -\item {} +\item {} If both are matrix-free, then the Newton and mass matrix \code{SUNLinearSolver} objects must be different. These may even use different solver algorithms (SPGMR, SPBCGS, etc.), if desired. @@ -4558,16 +4608,16 @@ \subsection{Mass matrix solver specification functions} template \code{SUNMatrix} object. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{LS} -- the \code{SUNLinearSolver} object to use. -\item {} +\item {} \emph{M} -- the template mass \code{SUNMatrix} object to use. -\item {} +\item {} \emph{time\_dep} -- flag denoting whether the mass matrix depends on the independent variable (\(M = M(t)\)) or not (\(M \ne M(t)\)). \code{SUNTRUE} indicates time-dependence of the @@ -4577,16 +4627,16 @@ \subsection{Mass matrix solver specification functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if ARKLS is incompatible with the provided \emph{LS} or \emph{M} input objects, or the current \code{N\_Vector} module. @@ -4651,25 +4701,25 @@ \subsection{Nonlinear solver interface functions} that ARKStep should use for implicit stage solves. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{NLS} -- the \code{SUNNonlinearSolver} object to use. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if ARKStep is incompatible with the provided \emph{NLS} input object. @@ -4704,29 +4754,29 @@ \subsection{Rootfinding initialization function} {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepCreate]{\emph{\code{ARKStepCreate()}}}}, and before {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nrtfn} -- number of functions \(g_i\), an integer \(\ge\) 0. -\item {} +\item {} \emph{g} -- name of user-supplied function, of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRootFn]{\emph{\code{ARKRootFn()}}}}, defining the functions \(g_i\) whose roots are sought. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if \emph{nrtfn} is greater than zero but \emph{g} = \code{NULL}. \end{itemize} @@ -4761,19 +4811,19 @@ \subsection{ARKStep solver function} Integrates the ODE over an interval in \(t\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{tout} -- the next time at which a computed solution is desired. -\item {} +\item {} \emph{yout} -- the computed solution vector. -\item {} +\item {} \emph{tret} -- the time corresponding to \emph{yout} (output). -\item {} +\item {} \emph{itask} -- a flag indicating the job of the solver for the next user step. @@ -4797,95 +4847,95 @@ \subsection{ARKStep solver function} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful. -\item {} +\item {} \emph{ARK\_ROOT\_RETURN} if {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}} succeeded, and found one or more roots. If the number of root functions, \emph{nrtfn}, is greater than 1, call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetRootInfo]{\emph{\code{ARKStepGetRootInfo()}}}} to see which \(g_i\) were found to have a root at (\emph{*tret}). -\item {} +\item {} \emph{ARK\_TSTOP\_RETURN} if {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}} succeeded and returned at \emph{tstop}. -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the \emph{arkode\_mem} argument was \code{NULL}. -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if one of the inputs to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}} is illegal, or some other input to the solver was either illegal or missing. Details will be provided in the error message. Typical causes of this failure: \begin{enumerate} -\item {} +\item {} A component of the error weight vector became zero during internal time-stepping. -\item {} +\item {} The linear solver initialization function (called by the user after calling {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepCreate]{\emph{\code{ARKStepCreate()}}}}) failed to set the linear solver-specific \emph{lsolve} field in \emph{arkode\_mem}. -\item {} +\item {} A root of one of the root functions was found both at a point \(t\) and also very near \(t\). -\item {} +\item {} The initial condition violates the inequality constraints. \end{enumerate} -\item {} +\item {} \emph{ARK\_TOO\_MUCH\_WORK} if the solver took \emph{mxstep} internal steps but could not reach \emph{tout}. The default value for \emph{mxstep} is \emph{MXSTEP\_DEFAULT = 500}. -\item {} +\item {} \emph{ARK\_TOO\_MUCH\_ACC} if the solver could not satisfy the accuracy demanded by the user for some internal step. -\item {} +\item {} \emph{ARK\_ERR\_FAILURE} if error test failures occurred either too many times (\emph{ark\_maxnef}) during one internal time step or occurred with \(|h| = h_{min}\). -\item {} +\item {} \emph{ARK\_CONV\_FAILURE} if either convergence test failures occurred too many times (\emph{ark\_maxncf}) during one internal time step or occurred with \(|h| = h_{min}\). -\item {} +\item {} \emph{ARK\_LINIT\_FAIL} if the linear solver's initialization function failed. -\item {} +\item {} \emph{ARK\_LSETUP\_FAIL} if the linear solver's setup routine failed in an unrecoverable manner. -\item {} +\item {} \emph{ARK\_LSOLVE\_FAIL} if the linear solver's solve routine failed in an unrecoverable manner. -\item {} +\item {} \emph{ARK\_MASSINIT\_FAIL} if the mass matrix solver's initialization function failed. -\item {} +\item {} \emph{ARK\_MASSSETUP\_FAIL} if the mass matrix solver's setup routine failed. -\item {} +\item {} \emph{ARK\_MASSSOLVE\_FAIL} if the mass matrix solver's solve routine failed. -\item {} +\item {} \emph{ARK\_VECTOROP\_ERR} a vector operation error occured. \end{itemize} @@ -4934,19 +4984,19 @@ \subsection{Optional input functions} The optional inputs are grouped into the following categories: \begin{itemize} -\item {} +\item {} General ARKStep options ({\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepinputtable]{\emph{\DUspan{}{Optional inputs for ARKStep}}}}), -\item {} +\item {} IVP method solver options ({\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepmethodinputtable]{\emph{\DUspan{}{Optional inputs for IVP method selection}}}}), -\item {} +\item {} Step adaptivity solver options ({\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepadaptivityinputtable]{\emph{\DUspan{}{Optional inputs for time step adaptivity}}}}), -\item {} +\item {} Implicit stage solver options ({\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstep-cinterface-arkstepsolverinputtable]{\emph{\DUspan{}{Optional inputs for implicit stage solves}}}}), -\item {} +\item {} Linear solver interface options ({\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arklsinputs]{\emph{\DUspan{}{Linear solver interface optional input functions}}}}), \end{itemize} @@ -4965,130 +5015,130 @@ \subsubsection{Optional inputs for ARKStep} \label{ARKStep_c_interface/User_callable:optional-inputs-for-arkstep}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepinputtable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Return ARKStep solver parameters to their defaults - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDefaults]{\emph{\code{ARKStepSetDefaults()}}}} - & + & internal \\ \hline Set dense output order - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDenseOrder]{\emph{\code{ARKStepSetDenseOrder()}}}} - & + & 3 \\ \hline Supply a pointer to a diagnostics output file - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDiagnostics]{\emph{\code{ARKStepSetDiagnostics()}}}} - & + & \code{NULL} \\ \hline Supply a pointer to an error output file - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetErrFile]{\emph{\code{ARKStepSetErrFile()}}}} - & + & \code{stderr} \\ \hline Supply a custom error handler function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetErrHandlerFn]{\emph{\code{ARKStepSetErrHandlerFn()}}}} - & + & internal fn \\ \hline Disable time step adaptivity (fixed-step mode) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetFixedStep]{\emph{\code{ARKStepSetFixedStep()}}}} - & + & disabled \\ \hline Supply an initial step size to attempt - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetInitStep]{\emph{\code{ARKStepSetInitStep()}}}} - & + & estimated \\ \hline Maximum no. of warnings for \(t_n+h = t_n\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxHnilWarns]{\emph{\code{ARKStepSetMaxHnilWarns()}}}} - & + & 10 \\ \hline Maximum no. of internal steps before \emph{tout} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNumSteps]{\emph{\code{ARKStepSetMaxNumSteps()}}}} - & + & 500 \\ \hline Maximum absolute step size - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxStep]{\emph{\code{ARKStepSetMaxStep()}}}} - & + & \(\infty\) \\ \hline Minimum absolute step size - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMinStep]{\emph{\code{ARKStepSetMinStep()}}}} - & + & 0.0 \\ \hline Set a value for \(t_{stop}\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetStopTime]{\emph{\code{ARKStepSetStopTime()}}}} - & + & \(\infty\) \\ \hline Supply a pointer for user data - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}} - & + & \code{NULL} \\ \hline Maximum no. of ARKStep error test failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxErrTestFails]{\emph{\code{ARKStepSetMaxErrTestFails()}}}} - & + & 7 \\ \hline Set `optimal' adaptivity parameters for a method - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetOptimalParams]{\emph{\code{ARKStepSetOptimalParams()}}}} - & + & internal \\ \hline Set inequality constraints on solution - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetConstraints]{\emph{\code{ARKStepSetConstraints()}}}} - & + & \code{NULL} \\ \hline Set max number of constraint failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNumConstrFails]{\emph{\code{ARKStepSetMaxNumConstrFails()}}}} - & + & 10 \\ \hline\end{tabulary} @@ -5101,19 +5151,19 @@ \subsubsection{Optional inputs for ARKStep} default values. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5137,22 +5187,22 @@ \subsubsection{Optional inputs for ARKStep} and implicit method predictors). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{dord} -- requested polynomial order of accuracy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5172,22 +5222,22 @@ \subsubsection{Optional inputs for ARKStep} all ARKStep step adaptivity and solver information is written. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{diagfp} -- pointer to the diagnostics output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5214,22 +5264,22 @@ \subsubsection{Optional inputs for ARKStep} function is used. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{errfp} -- pointer to the output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5256,26 +5306,26 @@ \subsubsection{Optional inputs for ARKStep} in handling error messages. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ehfun} -- name of user-supplied error handler function. -\item {} +\item {} \emph{eh\_data} -- pointer to user data passed to \emph{ehfun} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5295,22 +5345,22 @@ \subsubsection{Optional inputs for ARKStep} fixed time step size to use for all internal steps. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hfixed} -- value of the fixed step size to use. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5365,22 +5415,22 @@ \subsubsection{Optional inputs for ARKStep} initialization or re-initialization. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hin} -- value of the initial step to be attempted \((\ne 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5405,22 +5455,22 @@ \subsubsection{Optional inputs for ARKStep} ARKStep will instead return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mxhnil} -- maximum allowed number of warning messages \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5443,22 +5493,22 @@ \subsubsection{Optional inputs for ARKStep} will return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mxsteps} -- maximum allowed number of internal steps. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5479,22 +5529,22 @@ \subsubsection{Optional inputs for ARKStep} Specifies the upper bound on the magnitude of the time step size. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hmax} -- maximum absolute value of the time step size \((\ge 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5512,22 +5562,22 @@ \subsubsection{Optional inputs for ARKStep} Specifies the lower bound on the magnitude of the time step size. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hmin} -- minimum absolute value of the time step size \((\ge 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5546,22 +5596,22 @@ \subsubsection{Optional inputs for ARKStep} \(t\) past which the solution is not to proceed. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{tstop} -- stopping time for the integrator. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5580,22 +5630,22 @@ \subsubsection{Optional inputs for ARKStep} attaches it to the main ARKStep memory block. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{user\_data} -- pointer to the user data. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5620,22 +5670,22 @@ \subsubsection{Optional inputs for ARKStep} permitted in attempting one step, before returning with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{maxnef} -- maximum allowed number of error test failures \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5656,19 +5706,19 @@ \subsubsection{Optional inputs for ARKStep} a given method order. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5691,25 +5741,25 @@ \subsubsection{Optional inputs for ARKStep} solution vector \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{constraints} -- vector of constraint flags. If \code{constraints{[}i{]}} is \begin{itemize} -\item {} +\item {} 0.0 then no constraint is imposed on \(y_i\) -\item {} +\item {} 1.0 then \(y_i\) will be constrained to be \(y_i \geq 0.0\) -\item {} +\item {} -1.0 then \(y_i\) will be constrained to be \(y_i \leq 0.0\) -\item {} +\item {} 2.0 then \(y_i\) will be constrained to be \(y_i > 0.0\) -\item {} +\item {} -2.0 then \(y_i\) will be constrained to be \(y_i < 0.0\) \end{itemize} @@ -5717,13 +5767,13 @@ \subsubsection{Optional inputs for ARKStep} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if the constraints vector contains illegal values \end{itemize} @@ -5745,19 +5795,19 @@ \subsubsection{Optional inputs for ARKStep} will return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{maxfails} -- maximum allowed number of constrain failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} \end{itemize} @@ -5775,53 +5825,53 @@ \subsubsection{Optional inputs for IVP method selection} \label{ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepmethodinputtable}\label{ARKStep_c_interface/User_callable:optional-inputs-for-ivp-method-selection} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Set integrator method order - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetOrder]{\emph{\code{ARKStepSetOrder()}}}} - & + & 4 \\ \hline Specify implicit/explicit problem - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetImEx]{\emph{\code{ARKStepSetImEx()}}}} - & + & \code{SUNTRUE} \\ \hline Specify explicit problem - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetExplicit]{\emph{\code{ARKStepSetExplicit()}}}} - & + & \code{SUNFALSE} \\ \hline Specify implicit problem - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetImplicit]{\emph{\code{ARKStepSetImplicit()}}}} - & + & \code{SUNFALSE} \\ \hline Set additive RK tables - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}} - & + & internal \\ \hline Specify additive RK table numbers - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}} - & + & internal \\ \hline\end{tabulary} @@ -5834,22 +5884,22 @@ \subsubsection{Optional inputs for IVP method selection} method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ord} -- requested order of accuracy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5876,19 +5926,19 @@ \subsubsection{Optional inputs for IVP method selection} of problem are enabled, and to use an additive Runge Kutta method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5909,19 +5959,19 @@ \subsubsection{Optional inputs for IVP method selection} and to use an explicit RK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5946,19 +5996,19 @@ \subsubsection{Optional inputs for IVP method selection} and to use a diagonally implicit RK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -5979,31 +6029,31 @@ \subsubsection{Optional inputs for IVP method selection} or ARK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{q} -- global order of accuracy for the ARK method. -\item {} +\item {} \emph{p} -- global order of accuracy for the embedded ARK method. -\item {} +\item {} \emph{Bi} -- the Butcher table for the implicit RK method. -\item {} +\item {} \emph{Be} -- the Butcher table for the explicit RK method. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6053,25 +6103,25 @@ \subsubsection{Optional inputs for IVP method selection} or ARK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{itable} -- index of the DIRK Butcher table. -\item {} +\item {} \emph{etable} -- index of the ERK Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6112,95 +6162,95 @@ \subsubsection{Optional inputs for time step adaptivity} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Set a custom time step adaptivity function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityFn]{\emph{\code{ARKStepSetAdaptivityFn()}}}} - & + & internal \\ \hline Choose an existing time step adaptivity method - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityMethod]{\emph{\code{ARKStepSetAdaptivityMethod()}}}} - & + & 0 \\ \hline Explicit stability safety factor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetCFLFraction]{\emph{\code{ARKStepSetCFLFraction()}}}} - & + & 0.5 \\ \hline Time step error bias factor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetErrorBias]{\emph{\code{ARKStepSetErrorBias()}}}} - & + & 1.5 \\ \hline Bounds determining no change in step size - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetFixedStepBounds]{\emph{\code{ARKStepSetFixedStepBounds()}}}} - & + & 1.0 1.5 \\ \hline Maximum step growth factor on convergence fail - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxCFailGrowth]{\emph{\code{ARKStepSetMaxCFailGrowth()}}}} - & + & 0.25 \\ \hline Maximum step growth factor on error test fail - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxEFailGrowth]{\emph{\code{ARKStepSetMaxEFailGrowth()}}}} - & + & 0.3 \\ \hline Maximum first step growth factor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxFirstGrowth]{\emph{\code{ARKStepSetMaxFirstGrowth()}}}} - & + & 10000.0 \\ \hline Maximum general step growth factor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxGrowth]{\emph{\code{ARKStepSetMaxGrowth()}}}} - & + & 20.0 \\ \hline Time step safety factor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetSafetyFactor]{\emph{\code{ARKStepSetSafetyFactor()}}}} - & + & 0.96 \\ \hline Error fails before MaxEFailGrowth takes effect - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetSmallNumEFails]{\emph{\code{ARKStepSetSmallNumEFails()}}}} - & + & 2 \\ \hline Explicit stability function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetStabilityFn]{\emph{\code{ARKStepSetStabilityFn()}}}} - & + & none \\ \hline\end{tabulary} @@ -6208,30 +6258,30 @@ \subsubsection{Optional inputs for time step adaptivity} \index{ARKStepSetAdaptivityFn (C function)} \begin{fulllineitems} -\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityFn}\pysiglinewithargsret{int \bfcode{ARKStepSetAdaptivityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{ARKAdaptFn}}}\emph{ hfun}, void*\emph{ h\_data}}{} +\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityFn}\pysiglinewithargsret{int \bfcode{ARKStepSetAdaptivityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{ARKAdaptFn}}}\emph{ hfun}, void*\emph{ h\_data}}{} Sets a user-supplied time-step adaptivity function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hfun} -- name of user-supplied adaptivity function. -\item {} +\item {} \emph{h\_data} -- pointer to user data passed to \emph{hfun} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6251,44 +6301,44 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the method (and associated parameters) used for time step adaptivity. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{imethod} -- accuracy-based adaptivity method choice (0 \(\le\) \emph{imethod} \(\le\) 5): 0 is PID, 1 is PI, 2 is I, 3 is explicit Gustafsson, 4 is implicit Gustafsson, and 5 is the ImEx Gustafsson. -\item {} +\item {} \emph{idefault} -- flag denoting whether to use default adaptivity parameters (1), or that they will be supplied in the \emph{adapt\_params} argument (0). -\item {} +\item {} \emph{pq} -- flag denoting whether to use the embedding order of accuracy \emph{p} (0) or the method order of accuracy \emph{q} (1) within the adaptivity algorithm. \emph{p} is the default. -\item {} +\item {} \emph{adapt\_params{[}0{]}} -- \(k_1\) parameter within accuracy-based adaptivity algorithms. -\item {} +\item {} \emph{adapt\_params{[}1{]}} -- \(k_2\) parameter within accuracy-based adaptivity algorithms. -\item {} +\item {} \emph{adapt\_params{[}2{]}} -- \(k_3\) parameter within accuracy-based adaptivity algorithms. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6309,22 +6359,22 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the fraction of the estimated explicitly stable step to use. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{cfl\_frac} -- maximum allowed fraction of explicitly stable step (default is 0.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6344,23 +6394,23 @@ \subsubsection{Optional inputs for time step adaptivity} accuracy-based adaptivity strategies. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{bias} -- bias applied to error in accuracy-based time step estimation (default is 1.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6378,25 +6428,25 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the step growth interval in which the step size will remain unchanged. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lb} -- lower bound on window to leave step size fixed (default is 1.0). -\item {} +\item {} \emph{ub} -- upper bound on window to leave step size fixed (default is 1.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6415,23 +6465,23 @@ \subsubsection{Optional inputs for time step adaptivity} solver convergence failure on a stage solve within a step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{etacf} -- time step reduction factor on a nonlinear solver convergence failure (default is 0.25). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6450,22 +6500,22 @@ \subsubsection{Optional inputs for time step adaptivity} accuracy-based error failures in the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{etamxf} -- time step reduction factor on multiple error fails (default is 0.3). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6484,23 +6534,23 @@ \subsubsection{Optional inputs for time step adaptivity} first integration step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{etamx1} -- maximum allowed growth factor after the first time step (default is 10000.0). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6519,22 +6569,22 @@ \subsubsection{Optional inputs for time step adaptivity} steps in the integration process. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{growth} -- maximum allowed growth factor between consecutive time steps (default is 20.0). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6554,22 +6604,22 @@ \subsubsection{Optional inputs for time step adaptivity} estimated step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{safety} -- safety factor applied to accuracy-based time step (default is 0.96). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6590,22 +6640,22 @@ \subsubsection{Optional inputs for time step adaptivity} {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxEFailGrowth]{\emph{\code{ARKStepSetMaxEFailGrowth()}}}} is applied. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{small\_nef} -- bound to determine `multiple' for \emph{etamxf} (default is 2). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6619,31 +6669,31 @@ \subsubsection{Optional inputs for time step adaptivity} \index{ARKStepSetStabilityFn (C function)} \begin{fulllineitems} -\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepSetStabilityFn}\pysiglinewithargsret{int \bfcode{ARKStepSetStabilityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{ARKExpStabFn}}}\emph{ EStab}, void*\emph{ estab\_data}}{} +\phantomsection\label{ARKStep_c_interface/User_callable:c.ARKStepSetStabilityFn}\pysiglinewithargsret{int \bfcode{ARKStepSetStabilityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{ARKExpStabFn}}}\emph{ EStab}, void*\emph{ estab\_data}}{} Sets the problem-dependent function to estimate a stable time step size for the explicit portion of the ODE system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{EStab} -- name of user-supplied stability function. -\item {} +\item {} \emph{estab\_data} -- pointer to user data passed to \emph{EStab} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6669,67 +6719,67 @@ \subsubsection{Optional inputs for implicit stage solves} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Specify linearly implicit \(f^I\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetLinear]{\emph{\code{ARKStepSetLinear()}}}} - & + & \code{SUNFALSE} \\ \hline Specify nonlinearly implicit \(f^I\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinear]{\emph{\code{ARKStepSetNonlinear()}}}} - & + & \code{SUNTRUE} \\ \hline Implicit predictor method - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPredictorMethod]{\emph{\code{ARKStepSetPredictorMethod()}}}} - & + & 0 \\ \hline Maximum number of nonlinear iterations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNonlinIters]{\emph{\code{ARKStepSetMaxNonlinIters()}}}} - & + & 3 \\ \hline Coefficient in the nonlinear convergence test - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinConvCoef]{\emph{\code{ARKStepSetNonlinConvCoef()}}}} - & + & 0.1 \\ \hline Nonlinear convergence rate constant - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinCRDown]{\emph{\code{ARKStepSetNonlinCRDown()}}}} - & + & 0.3 \\ \hline Nonlinear residual divergence ratio - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinRDiv]{\emph{\code{ARKStepSetNonlinRDiv()}}}} - & + & 2.3 \\ \hline Maximum number of convergence failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxConvFails]{\emph{\code{ARKStepSetMaxConvFails()}}}} - & + & 10 \\ \hline\end{tabulary} @@ -6741,10 +6791,10 @@ \subsubsection{Optional inputs for implicit stage solves} Specifies that the implicit portion of the problem is linear. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{timedepend} -- flag denoting whether the Jacobian of \(f^I(t,y)\) is time-dependent (1) or not (0). Alternately, when using an iterative linear solver this flag @@ -6753,13 +6803,13 @@ \subsubsection{Optional inputs for implicit stage solves} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6786,19 +6836,19 @@ \subsubsection{Optional inputs for implicit stage solves} Specifies that the implicit portion of the problem is nonlinear. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6820,32 +6870,32 @@ \subsubsection{Optional inputs for implicit stage solves} Specifies the method to use for predicting implicit solutions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{method} -- method choice (0 \(\le\) \emph{method} \(\le\) 4): \begin{itemize} -\item {} +\item {} 0 is the trivial predictor, -\item {} +\item {} 1 is the maximum order (dense output) predictor, -\item {} +\item {} 2 is the variable order predictor, that decreases the polynomial degree for more distant RK stages, -\item {} +\item {} 3 is the cutoff order predictor, that uses the maximum order for early RK stages, and a first-order predictor for distant RK stages, -\item {} +\item {} 4 is the bootstrap predictor, that uses a second-order predictor based on only information within the current step. -\item {} +\item {} 5 is the minimum correction predictor, that uses all preceding stage information within the current step for prediction. @@ -6855,13 +6905,13 @@ \subsubsection{Optional inputs for implicit stage solves} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6881,25 +6931,25 @@ \subsubsection{Optional inputs for implicit stage solves} iterations permitted per RK stage within each time step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{maxcor} -- maximum allowed solver iterations per stage \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value or if the SUNNONLINSOL module is \code{NULL} -\item {} +\item {} \emph{ARK\_NLS\_OP\_ERR} if the SUNNONLINSOL object returned a failure flag \end{itemize} @@ -6919,22 +6969,22 @@ \subsubsection{Optional inputs for implicit stage solves} solver convergence test. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nlscoef} -- coefficient in nonlinear solver convergence test \((>0.0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6953,22 +7003,22 @@ \subsubsection{Optional inputs for implicit stage solves} Specifies the constant used in estimating the nonlinear solver convergence rate. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{crdown} -- nonlinear convergence rate estimation constant (default is 0.3). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -6987,23 +7037,23 @@ \subsubsection{Optional inputs for implicit stage solves} iteration will be declared divergent. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rdiv} -- tolerance on nonlinear correction size ratio to declare divergence (default is 2.3). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -7023,23 +7073,23 @@ \subsubsection{Optional inputs for implicit stage solves} an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{maxncf} -- maximum allowed nonlinear solver convergence failures per step \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -7122,32 +7172,32 @@ \subsubsection{Linear solver interface optional input functions} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Max change in step signaling new \(J\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDeltaGammaMax]{\emph{\code{ARKStepSetDeltaGammaMax()}}}} - & + & 0.2 \\ \hline Max steps between calls to ``lsetup'' routine - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxStepsBetweenLSet]{\emph{\code{ARKStepSetMaxStepsBetweenLSet()}}}} - & + & 20 \\ \hline Max steps between calls to new \(J\) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxStepsBetweenJac]{\emph{\code{ARKStepSetMaxStepsBetweenJac()}}}} - & + & 50 \\ \hline\end{tabulary} @@ -7160,23 +7210,23 @@ \subsubsection{Linear solver interface optional input functions} linear solver setup routine will be signaled. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{dgmax} -- tolerance on step size ratio change before calling linear solver setup routine (default is 0.2). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -7197,10 +7247,10 @@ \subsubsection{Linear solver interface optional input functions} solve; zero values reset to the default. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{msbp} -- maximum number of time steps between linear solver setup calls, or flag to force recomputation at each stage solve (default is 20). @@ -7208,10 +7258,10 @@ \subsubsection{Linear solver interface optional input functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} \end{itemize} @@ -7229,26 +7279,26 @@ \subsubsection{Linear solver interface optional input functions} preconditioner. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{msbj} -- maximum number of time steps between Jacobian or preconditioner updates (default is 50). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. \end{itemize} @@ -7270,32 +7320,32 @@ \subsubsection{Linear solver interface optional input functions} \label{ARKStep_c_interface/User_callable:optional-inputs-for-matrix-based-sunlinearsolver-modules}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arklsinputs-matrixbased} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Jacobian function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacFn]{\emph{\code{ARKStepSetJacFn()}}}} - & + & \code{DQ} \\ \hline Linear system function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetLinSysFn]{\emph{\code{ARKStepSetLinSysFn()}}}} - & + & internal \\ \hline Mass matrix function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassFn]{\emph{\code{ARKStepSetMassFn()}}}} - & + & none \\ \hline\end{tabulary} @@ -7343,22 +7393,22 @@ \subsubsection{Linear solver interface optional input functions} be used for the matrix-based solver with the ARKLS interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{jac} -- name of user-supplied Jacobian approximation function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -7387,22 +7437,22 @@ \subsubsection{Linear solver interface optional input functions} matrix-based solver with the ARKLS interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{linsys} -- name of user-supplied linear system approximation function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -7430,25 +7480,25 @@ \subsubsection{Linear solver interface optional input functions} matrix-based solver with the ARKLS interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mass} -- name of user-supplied mass matrix approximation function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_MASSMEM\_NULL} if the mass matrix solver memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -7473,25 +7523,25 @@ \subsubsection{Linear solver interface optional input functions} \label{ARKStep_c_interface/User_callable:optional-inputs-for-matrix-free-sunlinearsolver-modules}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arklsinputs-matrixfree} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline \(Jv\) functions (\emph{jtimes} and \emph{jtsetup}) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacTimes]{\emph{\code{ARKStepSetJacTimes()}}}} - & + & DQ, none \\ \hline \(Mv\) functions (\emph{mtimes} and \emph{mtsetup}) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassTimes]{\emph{\code{ARKStepSetMassTimes()}}}} - & + & none, none \\ \hline\end{tabulary} @@ -7538,32 +7588,32 @@ \subsubsection{Linear solver interface optional input functions} Specifies the Jacobian-times-vector setup and product functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{jtsetup} -- user-defined Jacobian-vector setup function. Pass \code{NULL} if no setup is necessary. -\item {} +\item {} \emph{jtimes} -- user-defined Jacobian-vector product function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. -\item {} +\item {} \emph{ARKLS\_SUNLS\_FAIL} if an error occurred when setting up the Jacobian-vector product in the \code{SUNLinearSolver} object used by the ARKLS interface. @@ -7594,36 +7644,36 @@ \subsubsection{Linear solver interface optional input functions} Specifies the mass matrix-times-vector setup and product functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mtsetup} -- user-defined mass matrix-vector setup function. Pass \code{NULL} if no setup is necessary. -\item {} +\item {} \emph{mtimes} -- user-defined mass matrix-vector product function. -\item {} +\item {} \emph{mtimes\_data} -- a pointer to user data, that will be supplied to both the \emph{mtsetup} and \emph{mtimes} functions. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_MASSMEM\_NULL} if the mass matrix solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. -\item {} +\item {} \emph{ARKLS\_SUNLS\_FAIL} if an error occurred when setting up the mass-matrix-vector product in the \code{SUNLinearSolver} object used by the ARKLS interface. @@ -7654,39 +7704,39 @@ \subsubsection{Linear solver interface optional input functions} \label{ARKStep_c_interface/User_callable:optional-inputs-for-iterative-sunlinearsolver-modules}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arklsinputs-iterative} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Newton preconditioning functions - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPreconditioner]{\emph{\code{ARKStepSetPreconditioner()}}}} - & + & \code{NULL}, \code{NULL} \\ \hline Mass matrix preconditioning functions - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassPreconditioner]{\emph{\code{ARKStepSetMassPreconditioner()}}}} - & + & \code{NULL}, \code{NULL} \\ \hline Newton linear and nonlinear tolerance ratio - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetEpsLin]{\emph{\code{ARKStepSetEpsLin()}}}} - & + & 0.05 \\ \hline Mass matrix linear and nonlinear tolerance ratio - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassEpsLin]{\emph{\code{ARKStepSetMassEpsLin()}}}} - & + & 0.05 \\ \hline\end{tabulary} @@ -7728,32 +7778,32 @@ \subsubsection{Linear solver interface optional input functions} Specifies the user-supplied preconditioner setup and solve functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{psetup} -- user defined preconditioner setup function. Pass \code{NULL} if no setup is needed. -\item {} +\item {} \emph{psolve} -- user-defined preconditioner solve function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. -\item {} +\item {} \emph{ARKLS\_SUNLS\_FAIL} if an error occurred when setting up preconditioning in the \code{SUNLinearSolver} object used by the ARKLS interface. @@ -7782,32 +7832,32 @@ \subsubsection{Linear solver interface optional input functions} Specifies the mass matrix preconditioner setup and solve functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{psetup} -- user defined preconditioner setup function. Pass \code{NULL} if no setup is to be done. -\item {} +\item {} \emph{psolve} -- user-defined preconditioner solve function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. -\item {} +\item {} \emph{ARKLS\_SUNLS\_FAIL} if an error occurred when setting up preconditioning in the \code{SUNLinearSolver} object used by the ARKLS interface. @@ -7838,25 +7888,25 @@ \subsubsection{Linear solver interface optional input functions} iteration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{eplifac} -- linear convergence safety factor. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. \end{itemize} @@ -7881,25 +7931,25 @@ \subsubsection{Linear solver interface optional input functions} linear iteration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{eplifac} -- linear convergence safety factor. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful. -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_MASSMEM\_NULL} if the mass matrix solver memory was \code{NULL}. -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value. \end{itemize} @@ -7925,25 +7975,25 @@ \subsubsection{Rootfinding optional input functions} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Direction of zero-crossings to monitor - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetRootDirection]{\emph{\code{ARKStepSetRootDirection()}}}} - & + & both \\ \hline Disable inactive root warnings - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNoInactiveRootWarn]{\emph{\code{ARKStepSetNoInactiveRootWarn()}}}} - & + & enabled \\ \hline\end{tabulary} @@ -7955,10 +8005,10 @@ \subsubsection{Rootfinding optional input functions} Specifies the direction of zero-crossings to be located and returned. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rootdir} -- state array of length \emph{nrtfn}, the number of root functions \(g_i\) (the value of \emph{nrtfn} was supplied in the call to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepRootInit]{\emph{\code{ARKStepRootInit()}}}}). If \code{rootdir{[}i{]} == @@ -7970,13 +8020,13 @@ \subsubsection{Rootfinding optional input functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -7995,16 +8045,16 @@ \subsubsection{Rootfinding optional input functions} to be identically zero at the beginning of the integration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} \end{itemize} @@ -8052,35 +8102,35 @@ \subsection{Interpolated output function} range \{0,...,*dord*\}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{t} -- the value of the independent variable at which the derivative is to be evaluated. -\item {} +\item {} \emph{k} -- the derivative order requested. -\item {} +\item {} \emph{dky} -- output vector (must be allocated by the user). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_BAD\_K} if \emph{k} is not in the range \{0,...,*dord*\}. -\item {} +\item {} \emph{ARK\_BAD\_T} if \emph{t} is not in the interval \([t_n-h_n, t_n]\) -\item {} +\item {} \emph{ARK\_BAD\_DKY} if the \emph{dky} vector was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory is \code{NULL} \end{itemize} @@ -8103,27 +8153,27 @@ \subsection{Optional output functions} ARKStep provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups: \begin{enumerate} -\item {} +\item {} SUNDIALS version information accessor routines are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-sunversioninfo]{\emph{\DUspan{}{SUNDIALS version information}}}}, -\item {} +\item {} General ARKStep output routines are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepmainoutputs]{\emph{\DUspan{}{Main solver optional output functions}}}}, -\item {} +\item {} ARKStep implicit solver output routines are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepimplicitsolveroutputs]{\emph{\DUspan{}{Implicit solver optional output functions}}}}, -\item {} +\item {} Output routines regarding root-finding results are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arksteprootoutputs]{\emph{\DUspan{}{Rootfinding optional output functions}}}}, -\item {} +\item {} Linear solver output routines are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arklsoutputs]{\emph{\DUspan{}{Linear solver interface optional output functions}}}} and -\item {} +\item {} General usability routines (e.g. to print the current ARKStep parameters, or output the current Butcher table(s)) are in the subsection {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepextraoutputs]{\emph{\DUspan{}{General usability functions}}}}. @@ -8136,20 +8186,20 @@ \subsection{Optional output functions} very useful in determining the efficiency of various methods inside ARKStep. For example: \begin{itemize} -\item {} +\item {} The counters \emph{nsteps}, \emph{nfe\_evals}, \emph{nfi\_evals} and \emph{nf\_evals} provide a rough measure of the overall cost of a given run, and can be compared between runs with different solver options to suggest which set of options is the most efficient. -\item {} +\item {} The ratio \emph{nniters/nsteps} measures the performance of the nonlinear iteration in solving the nonlinear systems at each stage, providing a measure of the degree of nonlinearity in the problem. Typical values of this for a Newton solver on a general problem range from 1.1 to 1.8. -\item {} +\item {} When using a Newton nonlinear solver, the ratio \emph{njevals/nniters} (in the case of a direct linear solver), and the ratio \emph{npevals/nniters} (in the case of an iterative linear solver) @@ -8157,7 +8207,7 @@ \subsection{Optional output functions} since these are updated infrequently, unless the Newton method convergence slows. -\item {} +\item {} When using a Newton nonlinear solver, the ratio \emph{njevals/nniters} (when using a direct linear solver), and the ratio \emph{nliters/nniters} (when using an iterative linear solver) can @@ -8167,12 +8217,12 @@ \subsection{Optional output functions} difference-quotient routine, it can indicate that the user-supplied Jacobian is inaccurate. -\item {} +\item {} The ratio \emph{expsteps/accsteps} can measure the quality of the ImEx splitting used, since a higher-quality splitting will be dominated by accuracy-limited steps. -\item {} +\item {} The ratio \emph{nsteps/step\_attempts} can measure the quality of the time step adaptivity algorithm, since a poor algorithm will result in more failed steps, and hence a lower ratio. @@ -8196,19 +8246,19 @@ \subsubsection{SUNDIALS version information} This routine fills a string with SUNDIALS version information. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{version} -- character array to hold the SUNDIALS version information. -\item {} +\item {} \emph{len} -- allocated length of the \emph{version} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS version \end{itemize} @@ -8229,28 +8279,28 @@ \subsubsection{SUNDIALS version information} release label if applicable. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{major} -- SUNDIALS release major version number. -\item {} +\item {} \emph{minor} -- SUNDIALS release minor version number. -\item {} +\item {} \emph{patch} -- SUNDIALS release patch version number. -\item {} +\item {} \emph{label} -- string to hold the SUNDIALS release label. -\item {} +\item {} \emph{len} -- allocated length of the \emph{label} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS label \end{itemize} @@ -8269,109 +8319,109 @@ \subsubsection{Main solver optional output functions} \label{ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepmainoutputs}\label{ARKStep_c_interface/User_callable:main-solver-optional-output-functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Size of ARKStep real and integer workspaces - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetWorkSpace]{\emph{\code{ARKStepGetWorkSpace()}}}} \\ \hline Cumulative number of internal steps - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumSteps]{\emph{\code{ARKStepGetNumSteps()}}}} \\ \hline Actual initial time step size used - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetActualInitStep]{\emph{\code{ARKStepGetActualInitStep()}}}} \\ \hline Step size used for the last successful step - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLastStep]{\emph{\code{ARKStepGetLastStep()}}}} \\ \hline Step size to be attempted on the next step - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetCurrentStep]{\emph{\code{ARKStepGetCurrentStep()}}}} \\ \hline Current internal time reached by the solver - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetCurrentTime]{\emph{\code{ARKStepGetCurrentTime()}}}} \\ \hline Suggested factor for tolerance scaling - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetTolScaleFactor]{\emph{\code{ARKStepGetTolScaleFactor()}}}} \\ \hline Error weight vector for state variables - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetErrWeights]{\emph{\code{ARKStepGetErrWeights()}}}} \\ \hline Residual weight vector - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetResWeights]{\emph{\code{ARKStepGetResWeights()}}}} \\ \hline Single accessor to many statistics at once - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetStepStats]{\emph{\code{ARKStepGetStepStats()}}}} \\ \hline Name of constant associated with a return flag - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetReturnFlagName]{\emph{\code{ARKStepGetReturnFlagName()}}}} \\ \hline No. of explicit stability-limited steps - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumExpSteps]{\emph{\code{ARKStepGetNumExpSteps()}}}} \\ \hline No. of accuracy-limited steps - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumAccSteps]{\emph{\code{ARKStepGetNumAccSteps()}}}} \\ \hline No. of attempted steps - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumStepAttempts]{\emph{\code{ARKStepGetNumStepAttempts()}}}} \\ \hline No. of calls to \emph{fe} and \emph{fi} functions - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumRhsEvals]{\emph{\code{ARKStepGetNumRhsEvals()}}}} \\ \hline No. of local error test failures that have occurred - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumErrTestFails]{\emph{\code{ARKStepGetNumErrTestFails()}}}} \\ \hline Current ERK and DIRK Butcher tables - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetCurrentButcherTables]{\emph{\code{ARKStepGetCurrentButcherTables()}}}} \\ \hline Estimated local truncation error vector - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetEstLocalErrors]{\emph{\code{ARKStepGetEstLocalErrors()}}}} \\ \hline Single accessor to many statistics at once - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetTimestepperStats]{\emph{\code{ARKStepGetTimestepperStats()}}}} \\ \hline Number of constraint test failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumConstrFails]{\emph{\code{ARKStepGetNumConstrFails()}}}} \\ \hline\end{tabulary} @@ -8383,22 +8433,22 @@ \subsubsection{Main solver optional output functions} Returns the ARKStep real and integer workspace sizes. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lenrw} -- the number of \code{realtype} values in the ARKStep workspace. -\item {} +\item {} \emph{leniw} -- the number of integer values in the ARKStep workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8415,19 +8465,19 @@ \subsubsection{Main solver optional output functions} the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nsteps} -- number of steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8443,19 +8493,19 @@ \subsubsection{Main solver optional output functions} Returns the value of the integration step size used on the first step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hinused} -- actual value of initial step size. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8480,19 +8530,19 @@ \subsubsection{Main solver optional output functions} internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hlast} -- step size taken on the last internal step. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8508,19 +8558,19 @@ \subsubsection{Main solver optional output functions} Returns the integration step size to be attempted on the next internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{hcur} -- step size to be attempted on the next internal step. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8536,19 +8586,19 @@ \subsubsection{Main solver optional output functions} Returns the current internal time reached by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{tcur} -- current internal time reached. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8566,19 +8616,19 @@ \subsubsection{Main solver optional output functions} requested for some internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{tolsfac} -- suggested scaling factor for user-supplied tolerances. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8594,19 +8644,19 @@ \subsubsection{Main solver optional output functions} Returns the current error weight vector. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{eweight} -- solution error weights at the current time. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8625,19 +8675,19 @@ \subsubsection{Main solver optional output functions} Returns the current residual weight vector. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rweight} -- residual error weights at the current time. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8656,31 +8706,31 @@ \subsubsection{Main solver optional output functions} Returns many of the most useful optional outputs in a single call. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nsteps} -- number of steps taken in the solver. -\item {} +\item {} \emph{hinused} -- actual value of initial step size. -\item {} +\item {} \emph{hlast} -- step size taken on the last internal step. -\item {} +\item {} \emph{hcur} -- step size to be attempted on the next internal step. -\item {} +\item {} \emph{tcur} -- current internal time reached. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8696,7 +8746,7 @@ \subsubsection{Main solver optional output functions} Returns the name of the ARKStep constant corresponding to \emph{flag}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{flag} -- a return flag from an ARKStep function. \end{itemize} @@ -8717,19 +8767,19 @@ \subsubsection{Main solver optional output functions} taken by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{expsteps} -- number of stability-limited steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8746,19 +8796,19 @@ \subsubsection{Main solver optional output functions} taken by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{accsteps} -- number of accuracy-limited steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8774,19 +8824,19 @@ \subsubsection{Main solver optional output functions} Returns the cumulative number of steps attempted by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{step\_attempts} -- number of steps attempted by solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8803,22 +8853,22 @@ \subsubsection{Main solver optional output functions} side functions, \(f^E\) and \(f^I\) (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nfe\_evals} -- number of calls to the user's \(f^E(t,y)\) function. -\item {} +\item {} \emph{nfi\_evals} -- number of calls to the user's \(f^I(t,y)\) function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8838,19 +8888,19 @@ \subsubsection{Main solver optional output functions} have occurred (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{netfails} -- number of error test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8867,22 +8917,22 @@ \subsubsection{Main solver optional output functions} currently in use by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{Bi} -- pointer to implicit Butcher table structure. -\item {} +\item {} \emph{Be} -- pointer to explicit Butcher table structure. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8918,19 +8968,19 @@ \subsubsection{Main solver optional output functions} for the current step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ele} -- vector of estimated local truncation errors. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -8961,37 +9011,37 @@ \subsubsection{Main solver optional output functions} Returns many of the most useful time-stepper statistics in a single call. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{expsteps} -- number of stability-limited steps taken in the solver. -\item {} +\item {} \emph{accsteps} -- number of accuracy-limited steps taken in the solver. -\item {} +\item {} \emph{step\_attempts} -- number of steps attempted by the solver. -\item {} +\item {} \emph{nfe\_evals} -- number of calls to the user's \(f^E(t,y)\) function. -\item {} +\item {} \emph{nfi\_evals} -- number of calls to the user's \(f^I(t,y)\) function. -\item {} +\item {} \emph{nlinsetups} -- number of linear solver setup calls made. -\item {} +\item {} \emph{netfails} -- number of error test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9007,19 +9057,19 @@ \subsubsection{Main solver optional output functions} Returns the cumulative number of constraint test failures (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nconstrfails} -- number of constraint test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9034,29 +9084,29 @@ \subsubsection{Implicit solver optional output functions} \label{ARKStep_c_interface/User_callable:implicit-solver-optional-output-functions}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arkstepimplicitsolveroutputs} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline No. of calls to linear solver setup function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumLinSolvSetups]{\emph{\code{ARKStepGetNumLinSolvSetups()}}}} \\ \hline No. of nonlinear solver iterations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumNonlinSolvIters]{\emph{\code{ARKStepGetNumNonlinSolvIters()}}}} \\ \hline No. of nonlinear solver convergence failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumNonlinSolvConvFails]{\emph{\code{ARKStepGetNumNonlinSolvConvFails()}}}} \\ \hline Single accessor to all nonlinear solver statistics - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNonlinSolvStats]{\emph{\code{ARKStepGetNonlinSolvStats()}}}} \\ \hline\end{tabulary} @@ -9069,19 +9119,19 @@ \subsubsection{Implicit solver optional output functions} setup routine (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nlinsetups} -- number of linear solver setup calls made. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9102,22 +9152,22 @@ \subsubsection{Implicit solver optional output functions} performed (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nniters} -- number of nonlinear iterations performed. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NLS\_OP\_ERR} if the SUNNONLINSOL object returned a failure flag \end{itemize} @@ -9138,19 +9188,19 @@ \subsubsection{Implicit solver optional output functions} failures that have occurred (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nncfails} -- number of nonlinear convergence failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9170,25 +9220,25 @@ \subsubsection{Implicit solver optional output functions} Returns all of the nonlinear solver statistics in a single call. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nniters} -- number of nonlinear iterations performed. -\item {} +\item {} \emph{nncfails} -- number of nonlinear convergence failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NLS\_OP\_ERR} if the SUNNONLINSOL object returned a failure flag \end{itemize} @@ -9207,19 +9257,19 @@ \subsubsection{Rootfinding optional output functions} \label{ARKStep_c_interface/User_callable:rootfinding-optional-output-functions}\label{ARKStep_c_interface/User_callable:arkstep-cinterface-arksteprootoutputs} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Array showing roots found - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetRootInfo]{\emph{\code{ARKStepGetRootInfo()}}}} \\ \hline No. of calls to user root function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumGEvals]{\emph{\code{ARKStepGetNumGEvals()}}}} \\ \hline\end{tabulary} @@ -9232,10 +9282,10 @@ \subsubsection{Rootfinding optional output functions} have a root. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{rootsfound} -- array of length \emph{nrtfn} with the indices of the user functions \(g_i\) found to have a root (the value of \emph{nrtfn} was supplied in the call to @@ -9246,10 +9296,10 @@ \subsubsection{Rootfinding optional output functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9274,19 +9324,19 @@ \subsubsection{Rootfinding optional output functions} user's root function \(g\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ngevals} -- number of calls made to \(g\) so far. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -9318,119 +9368,119 @@ \subsubsection{Linear solver interface optional output functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Size of real and integer workspaces - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLinWorkSpace]{\emph{\code{ARKStepGetLinWorkSpace()}}}} \\ \hline No. of Jacobian evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumJacEvals]{\emph{\code{ARKStepGetNumJacEvals()}}}} \\ \hline No. of preconditioner evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumPrecEvals]{\emph{\code{ARKStepGetNumPrecEvals()}}}} \\ \hline No. of preconditioner solves - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumPrecSolves]{\emph{\code{ARKStepGetNumPrecSolves()}}}} \\ \hline No. of linear iterations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumLinIters]{\emph{\code{ARKStepGetNumLinIters()}}}} \\ \hline No. of linear convergence failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumLinConvFails]{\emph{\code{ARKStepGetNumLinConvFails()}}}} \\ \hline No. of Jacobian-vector setup evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumJTSetupEvals]{\emph{\code{ARKStepGetNumJTSetupEvals()}}}} \\ \hline No. of Jacobian-vector product evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumJtimesEvals]{\emph{\code{ARKStepGetNumJtimesEvals()}}}} \\ \hline No. of \emph{fi} calls for finite diff. \(J\) or \(Jv\) evals. - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumLinRhsEvals]{\emph{\code{ARKStepGetNumLinRhsEvals()}}}} \\ \hline Last return from a linear solver function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLastLinFlag]{\emph{\code{ARKStepGetLastLinFlag()}}}} \\ \hline Name of constant associated with a return flag - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLinReturnFlagName]{\emph{\code{ARKStepGetLinReturnFlagName()}}}} \\ \hline Size of real and integer mass matrix solver workspaces - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetMassWorkSpace]{\emph{\code{ARKStepGetMassWorkSpace()}}}} \\ \hline No. of mass matrix solver setups (incl. \(M\) evals.) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassSetups]{\emph{\code{ARKStepGetNumMassSetups()}}}} \\ \hline No. of mass matrix multiply setups - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassMultSetups]{\emph{\code{ARKStepGetNumMassMultSetups()}}}} \\ \hline No. of mass matrix multiplies - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassMult]{\emph{\code{ARKStepGetNumMassMult()}}}} \\ \hline No. of mass matrix solves - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassSolves]{\emph{\code{ARKStepGetNumMassSolves()}}}} \\ \hline No. of mass matrix preconditioner evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassPrecEvals]{\emph{\code{ARKStepGetNumMassPrecEvals()}}}} \\ \hline No. of mass matrix preconditioner solves - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassPrecSolves]{\emph{\code{ARKStepGetNumMassPrecSolves()}}}} \\ \hline No. of mass matrix linear iterations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassIters]{\emph{\code{ARKStepGetNumMassIters()}}}} \\ \hline No. of mass matrix solver convergence failures - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMassConvFails]{\emph{\code{ARKStepGetNumMassConvFails()}}}} \\ \hline No. of mass-matrix-vector setup evaluations - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumMTSetups]{\emph{\code{ARKStepGetNumMTSetups()}}}} \\ \hline Last return from a mass matrix solver function - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLastMassFlag]{\emph{\code{ARKStepGetLastMassFlag()}}}} \\ \hline\end{tabulary} @@ -9442,25 +9492,25 @@ \subsubsection{Linear solver interface optional output functions} Returns the real and integer workspace used by the ARKLS linear solver interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lenrwLS} -- the number of \code{realtype} values in the ARKLS workspace. -\item {} +\item {} \emph{leniwLS} -- the number of integer values in the ARKLS workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9485,22 +9535,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the number of calls made to the Jacobian approximation routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{njevals} -- number of calls to the Jacobian function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9517,22 +9567,22 @@ \subsubsection{Linear solver interface optional output functions} i.e. the number of calls made to \emph{psetup} with \emph{jok} = \code{SUNFALSE}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{npevals} -- the current number of calls to \emph{psetup}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9549,22 +9599,22 @@ \subsubsection{Linear solver interface optional output functions} solve function, \emph{psolve}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{npsolves} -- the number of calls to \emph{psolve}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9580,22 +9630,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the cumulative number of linear iterations. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nliters} -- the current number of linear iterations. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9615,22 +9665,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the cumulative number of linear convergence failures. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nlcfails} -- the current number of linear convergence failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9647,22 +9697,22 @@ \subsubsection{Linear solver interface optional output functions} Jacobian-vector setup function, \emph{jtsetup}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{njtsetup} -- the current number of calls to \emph{jtsetup}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9679,22 +9729,22 @@ \subsubsection{Linear solver interface optional output functions} Jacobian-vector product function, \emph{jtimes}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{njvevals} -- the current number of calls to \emph{jtimes}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9712,23 +9762,23 @@ \subsubsection{Linear solver interface optional output functions} Jacobian or Jacobian-vector product approximation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nfevalsLS} -- the number of calls to the user implicit right-hand side function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9747,23 +9797,23 @@ \subsubsection{Linear solver interface optional output functions} Returns the last return value from an ARKLS routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lsflag} -- the value of the last return flag from an ARKLS function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9808,7 +9858,7 @@ \subsubsection{Linear solver interface optional output functions} Returns the name of the ARKLS constant corresponding to \emph{lsflag}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{lsflag} -- a return flag from an ARKLS function. \end{itemize} @@ -9829,25 +9879,25 @@ \subsubsection{Linear solver interface optional output functions} Returns the real and integer workspace used by the ARKLS mass matrix linear solver interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lenrwMLS} -- the number of \code{realtype} values in the ARKLS mass solver workspace. -\item {} +\item {} \emph{leniwMLS} -- the number of integer values in the ARKLS mass solver workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9874,22 +9924,22 @@ \subsubsection{Linear solver interface optional output functions} mass-matrix constructor function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmsetups} -- number of calls to the mass matrix solver setup routine. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9906,22 +9956,22 @@ \subsubsection{Linear solver interface optional output functions} (matrix-based solvers) routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmvsetups} -- number of calls to the mass matrix matrix-times-vector setup routine. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9939,22 +9989,22 @@ \subsubsection{Linear solver interface optional output functions} routine (matris-free solvers). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmmults} -- number of calls to the mass matrix solver matrix-times-vector routine. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -9970,22 +10020,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the number of calls made to the ARKLS mass matrix solver `solve' routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmsolves} -- number of calls to the mass matrix solver solve routine. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10002,22 +10052,22 @@ \subsubsection{Linear solver interface optional output functions} i.e. the number of calls made to \emph{psetup}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmpevals} -- the current number of calls to \emph{psetup}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10034,22 +10084,22 @@ \subsubsection{Linear solver interface optional output functions} solve function, \emph{psolve}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmpsolves} -- the number of calls to \emph{psolve}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10065,22 +10115,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the cumulative number of mass matrix solver iterations. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmiters} -- the current number of mass matrix solver linear iterations. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10096,22 +10146,22 @@ \subsubsection{Linear solver interface optional output functions} Returns the cumulative number of mass matrix solver convergence failures. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmcfails} -- the current number of mass matrix solver convergence failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10128,22 +10178,22 @@ \subsubsection{Linear solver interface optional output functions} mass-matrix-vector product setup function, \emph{mtsetup}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nmtsetup} -- the current number of calls to \emph{mtsetup}. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10159,23 +10209,23 @@ \subsubsection{Linear solver interface optional output functions} Returns the last return value from an ARKLS mass matrix interface routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mlsflag} -- the value of the last return flag from an ARKLS mass matrix solver interface function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory was \code{NULL} \end{itemize} @@ -10202,19 +10252,19 @@ \subsubsection{General usability functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional routine -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Output all ARKStep solver parameters - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepWriteParameters]{\emph{\code{ARKStepWriteParameters()}}}} \\ \hline Output the current Butcher table(s) - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepWriteButcher]{\emph{\code{ARKStepWriteButcher()}}}} \\ \hline\end{tabulary} @@ -10226,19 +10276,19 @@ \subsubsection{General usability functions} Outputs all ARKStep solver parameters to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the solver parameters. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -10261,19 +10311,19 @@ \subsubsection{General usability functions} Outputs the current Butcher table(s) to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the Butcher table(s). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -10349,38 +10399,38 @@ \subsection{ARKStep re-initialization functions} ARKStep time-stepper module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{fe} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the explicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\). -\item {} +\item {} \emph{fi} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the implicit portion of the right-hand side function in \(M\, \dot{y} = f^E(t,y) + f^I(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if a memory allocation failed -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -10435,42 +10485,42 @@ \subsection{ARKStep system resize function} comparable dynamical time scale. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ynew} -- the newly-sized solution vector, holding the current dependent variable values \(y(t_0)\). -\item {} +\item {} \emph{hscale} -- the desired scaling factor for the dynamical time scale (i.e. the next step will be of size \emph{h*hscale}). -\item {} +\item {} \emph{t0} -- the current value of the independent variable \(t_0\) (this must be consistent with \emph{ynew}). -\item {} +\item {} \emph{resize} -- the user-supplied vector resize function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKVecResizeFn]{\emph{\code{ARKVecResizeFn()}}}}. -\item {} +\item {} \emph{resize\_data} -- the user-supplied data structure to be passed to \emph{resize} when modifying internal ARKStep vectors. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -10529,52 +10579,52 @@ \section{User-supplied functions} \label{ARKStep_c_interface/User_supplied:arkstep-cinterface-usersupplied}\label{ARKStep_c_interface/User_supplied:user-supplied-functions}\label{ARKStep_c_interface/User_supplied::doc} The user-supplied functions for ARKStep consist of: \begin{itemize} -\item {} +\item {} at least one function defining the ODE (required), -\item {} +\item {} a function that handles error and warning messages (optional), -\item {} +\item {} a function that provides the error weight vector (optional), -\item {} +\item {} a function that provides the residual weight vector (optional), -\item {} +\item {} a function that handles adaptive time step error control (optional), -\item {} +\item {} a function that handles explicit time step stability (optional), -\item {} +\item {} a function that defines the root-finding problem(s) to solve (optional), -\item {} +\item {} one or two functions that provide Jacobian-related information for the linear solver, if a Newton-based nonlinear iteration is chosen (optional), -\item {} +\item {} one or two functions that define the preconditioner for use in any of the Krylov iterative algorithms, if a Newton-based nonlinear iteration and iterative linear solver are chosen (optional), and -\item {} +\item {} if the problem involves a non-identity mass matrix \(M\ne I\): \begin{itemize} -\item {} +\item {} one or two functions that provide mass-matrix-related information for the linear and mass matrix solvers (required), -\item {} +\item {} one or two functions that define the mass matrix preconditioner for use in an iterative mass matrix solver is chosen (optional), and \end{itemize} -\item {} +\item {} a function that handles vector resizing operations, if the underlying vector structure supports resizing (as opposed to deletion/recreation), and if the user plans to call @@ -10595,16 +10645,16 @@ \subsection{ODE right-hand side} value of the independent variable \(t\) and state vector \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{ydot} -- the output vector that forms a portion of the ODE RHS \(f^E(t,y) + f^I(t,y)\). -\item {} +\item {} \emph{user\_data} -- the \emph{user\_data} pointer that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. \end{itemize} @@ -10651,19 +10701,19 @@ \subsection{Error message handler function} ARKStep and its sub-modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{error\_code} -- the error code. -\item {} +\item {} \emph{module} -- the name of the ARKStep module reporting the error. -\item {} +\item {} \emph{function} -- the name of the function in which the error occurred. -\item {} +\item {} \emph{msg} -- the error message. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{eh\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetErrHandlerFn]{\emph{\code{ARKStepSetErrHandlerFn()}}}}. @@ -10686,7 +10736,7 @@ \subsection{Error message handler function} \subsection{Error weight function} \label{ARKStep_c_interface/User_supplied:arkstep-cinterface-errorweight}\label{ARKStep_c_interface/User_supplied:error-weight-function} As an alternative to providing the relative and absolute tolerances, -the user may provide a function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn}}}} to compute a +the user may provide a function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn}}}} to compute a vector \emph{ewt} containing the weights in the WRMS norm \(\|v\|_{WRMS} = \left(\frac{1}{n} \sum_{i=1}^n \left(ewt_i\; v_i\right)^2 \right)^{1/2}\). These weights will be used in place of those defined @@ -10699,14 +10749,14 @@ \subsection{Error weight function} \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the dependent variable vector at which the weight vector is to be computed. -\item {} +\item {} \emph{ewt} -- the output vector containing the error weights. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -10745,14 +10795,14 @@ \subsection{Residual weight function} \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the dependent variable vector at which the weight vector is to be computed. -\item {} +\item {} \emph{rwt} -- the output vector containing the residual weights. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -10778,7 +10828,7 @@ \subsection{Time step adaptivity function} \label{ARKStep_c_interface/User_supplied:arkstep-cinterface-adaptivityfn}\label{ARKStep_c_interface/User_supplied:time-step-adaptivity-function} As an alternative to using one of the built-in time step adaptivity methods for controlling solution error, the user may provide a -function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn}}}} to compute a target step size +function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn}}}} to compute a target step size \(h\) for the next integration step. These steps should be chosen as the maximum value such that the error estimates remain below 1. \index{ARKAdaptFn (C type)} @@ -10789,40 +10839,40 @@ \subsection{Time step adaptivity function} that chooses \(h\) satisfying the error tolerances. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{h1} -- the current step size, \(t_n - t_{n-1}\). -\item {} +\item {} \emph{h2} -- the previous step size, \(t_{n-1} - t_{n-2}\). -\item {} +\item {} \emph{h3} -- the step size \(t_{n-2}-t_{n-3}\). -\item {} +\item {} \emph{e1} -- the error estimate from the current step, \(n\). -\item {} +\item {} \emph{e2} -- the error estimate from the previous step, \(n-1\). -\item {} +\item {} \emph{e3} -- the error estimate from the step \(n-2\). -\item {} +\item {} \emph{q} -- the global order of accuracy for the method. -\item {} +\item {} \emph{p} -- the global order of accuracy for the embedded method. -\item {} +\item {} \emph{hnew} -- the output value of the next step size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{h\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityFn]{\emph{\code{ARKStepSetAdaptivityFn()}}}}. @@ -10845,7 +10895,7 @@ \subsection{Explicit stability function} the accuracy-based time step adaptivity algorithms may be sufficient for retaining a stable solution to the ODE system, these may be inefficient if \(f^E(t,y)\) contains moderately stiff terms. In -this scenario, a user may provide a function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn}}}} +this scenario, a user may provide a function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn}}}} to provide this stability information to ARKStep. This function must set the scalar step size satisfying the stability restriction for the upcoming time step. This value will subsequently be bounded by @@ -10859,17 +10909,17 @@ \subsection{Explicit stability function} explicit portions of the ImEx ODE system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{hstab} -- the output value with the absolute value of the maximum stable step size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{estab\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetStabilityFn]{\emph{\code{ARKStepSetStabilityFn()}}}}. @@ -10903,16 +10953,16 @@ \subsection{Rootfinding function} \(g_i(t,y)\) are sought. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{gout} -- the output array, of length \emph{nrtfn}, with components \(g_i(t,y)\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -10947,24 +10997,24 @@ \subsection{Jacobian construction (matrix-based linear solvers)} \frac{\partial f^I}{\partial y}\) (or an approximation to it). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector, namely the predicted value of \(y(t)\). -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{Jac} -- the output Jacobian matrix. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. -\item {} +\item {} \emph{tmp1}, \emph{tmp2}, \emph{tmp3} -- pointers to memory allocated to variables of type \code{N\_Vector} which can be used by an ARKLsJacFn as temporary storage or work space. @@ -11093,23 +11143,23 @@ \subsection{Jacobian construction (matrix-based linear solvers)} an approximation to it). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector, namely the predicted value of \(y(t)\). -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{A} -- the output linear system matrix. -\item {} +\item {} \emph{M} -- the current mass matrix (this input is \code{NULL} if \(M = I\)). -\item {} +\item {} \emph{jok} -- is an input flag indicating whether the Jacobian-related data needs to be updated. The \emph{jok} argument provides for the reuse of Jacobian data in the preconditioner solve function. When \emph{jok} = @@ -11119,20 +11169,20 @@ \subsection{Jacobian construction (matrix-based linear solvers)} \emph{gamma}). A call with \emph{jok} = \code{SUNTRUE} can only occur after a call with \emph{jok} = \code{SUNFALSE}. -\item {} +\item {} \emph{jcur} -- is a pointer to a flag which should be set to \code{SUNTRUE} if Jacobian data was recomputed, or set to \code{SUNFALSE} if Jacobian data was not recomputed, but saved data was still reused. -\item {} +\item {} \emph{gamma} -- the scalar \(\gamma\) appearing in the Newton matrix given by \(A=I-\gamma J\) or \(A=M-\gamma J\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. -\item {} +\item {} \emph{tmp1}, \emph{tmp2}, \emph{tmp3} -- pointers to memory allocated to variables of type \code{N\_Vector} which can be used by an ARKLsLinSysFn as temporary storage or work space. @@ -11170,26 +11220,26 @@ \subsection{Jacobian-vector product (matrix-free linear solvers)} \left(\frac{\partial f^I}{\partial y}\right)v\) (or an approximation to it). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{v} -- the vector to multiply. -\item {} +\item {} \emph{Jv} -- the output vector computed. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. -\item {} +\item {} \emph{tmp} -- pointer to memory allocated to a variable of type \code{N\_Vector} which can be used as temporary storage or work space. @@ -11231,16 +11281,16 @@ \subsection{Jacobian-vector product setup (matrix-free linear solvers)} data needed by the Jacobian-times-vector routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -11293,26 +11343,26 @@ \subsection{Preconditioner solve (iterative linear solvers)} This function solves the preconditioner system \(Pz=r\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{r} -- the right-hand side vector of the linear system. -\item {} +\item {} \emph{z} -- the computed output solution vector. -\item {} +\item {} \emph{gamma} -- the scalar \(\gamma\) appearing in the Newton matrix given by \(A=M-\gamma J\). -\item {} +\item {} \emph{delta} -- an input tolerance to be used if an iterative method is employed in the solution. In that case, the residual vector \(Res = r-Pz\) of the system should be made to be less than \emph{delta} @@ -11321,12 +11371,12 @@ \subsection{Preconditioner solve (iterative linear solvers)} \emph{delta}. To obtain the \code{N\_Vector} \emph{ewt}, call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetErrWeights]{\emph{\code{ARKStepGetErrWeights()}}}}. -\item {} +\item {} \emph{lr} -- an input flag indicating whether the preconditioner solve is to use the left preconditioner (\emph{lr} = 1) or the right preconditioner (\emph{lr} = 2). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -11358,16 +11408,16 @@ \subsection{Preconditioner setup (iterative linear solvers)} data needed by the preconditioner. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{fy} -- the current value of the vector \(f^I(t,y)\). -\item {} +\item {} \emph{jok} -- is an input flag indicating whether the Jacobian-related data needs to be updated. The \emph{jok} argument provides for the reuse of Jacobian data in the preconditioner solve function. When @@ -11377,16 +11427,16 @@ \subsection{Preconditioner setup (iterative linear solvers)} value of \emph{gamma}). A call with \emph{jok} = \code{SUNTRUE} can only occur after a call with \emph{jok} = \code{SUNFALSE}. -\item {} +\item {} \emph{jcurPtr} -- is a pointer to a flag which should be set to \code{SUNTRUE} if Jacobian data was recomputed, or set to \code{SUNFALSE} if Jacobian data was not recomputed, but saved data was still reused. -\item {} +\item {} \emph{gamma} -- the scalar \(\gamma\) appearing in the Newton matrix given by \(A=M-\gamma J\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -11444,17 +11494,17 @@ \subsection{Mass matrix construction (matrix-based linear solvers)} This function computes the mass matrix \(M\) (or an approximation to it). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{M} -- the output mass matrix. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. -\item {} +\item {} \emph{tmp1}, \emph{tmp2}, \emph{tmp3} -- pointers to memory allocated to variables of type \code{N\_Vector} which can be used by an ARKLsMassFn as temporary storage or work space. @@ -11539,16 +11589,16 @@ \subsection{Mass matrix-vector product (matrix-free linear solvers)} This function computes the product \(M*v\) (or an approximation to it). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{v} -- the vector to multiply. -\item {} +\item {} \emph{Mv} -- the output vector computed. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{mtimes\_data} -- a pointer to user data, the same as the \emph{mtimes\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassTimes]{\emph{\code{ARKStepSetMassTimes()}}}}. @@ -11580,10 +11630,10 @@ \subsection{Mass matrix-vector product setup (matrix-free linear solvers)} data needed by the mass-matrix-times-vector routine. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{mtimes\_data} -- a pointer to user data, the same as the \emph{mtimes\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassTimes]{\emph{\code{ARKStepSetMassTimes()}}}}. @@ -11618,16 +11668,16 @@ \subsection{Mass matrix preconditioner solve (iterative linear solvers)} This function solves the preconditioner system \(Pz=r\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{r} -- the right-hand side vector of the linear system. -\item {} +\item {} \emph{z} -- the computed output solution vector. -\item {} +\item {} \emph{delta} -- an input tolerance to be used if an iterative method is employed in the solution. In that case, the residual vector \(Res = r-Pz\) of the system should be made to be less than \emph{delta} @@ -11636,12 +11686,12 @@ \subsection{Mass matrix preconditioner solve (iterative linear solvers)} \emph{delta}. To obtain the \code{N\_Vector} \emph{ewt}, call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetErrWeights]{\emph{\code{ARKStepGetErrWeights()}}}}. -\item {} +\item {} \emph{lr} -- an input flag indicating whether the preconditioner solve is to use the left preconditioner (\emph{lr} = 1) or the right preconditioner (\emph{lr} = 2). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -11674,10 +11724,10 @@ \subsection{Mass matrix preconditioner setup (iterative linear solvers)} data needed by the preconditioner. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -11733,13 +11783,13 @@ \subsection{Vector resize function} supplied vector, \emph{ytemplate}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the vector to resize. -\item {} +\item {} \emph{ytemplate} -- a vector of the desired size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{resize\_data} parameter that was passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResize]{\emph{\code{ARKStepResize()}}}}. @@ -11806,34 +11856,34 @@ \subsubsection{ARKBANDPRE usage} skeleton program presented in {\hyperref[ARKStep_c_interface/Skeleton:arkstep-cinterface-skeleton]{\emph{\DUspan{}{A skeleton of the user's main program}}}} are \emph{italicized}. \begin{enumerate} -\item {} +\item {} \emph{Initialize multi-threaded environment (if appropriate)} -\item {} +\item {} \emph{Set problem dimensions} -\item {} +\item {} \emph{Set vector of initial values} -\item {} +\item {} \emph{Create ARKStep object} -\item {} +\item {} \emph{Specify integration tolerances} -\item {} +\item {} Create iterative linear solver object When creating the iterative linear solver object, specify the type of preconditioning (\code{PREC\_LEFT} or \code{PREC\_RIGHT}) to use. -\item {} +\item {} \emph{Set linear solver optional inputs} -\item {} +\item {} \emph{Attach linear solver module} -\item {} +\item {} Initialize the ARKBANDPRE preconditioner module \begin{quote} @@ -11846,29 +11896,29 @@ \subsubsection{ARKBANDPRE usage} data. \end{quote} -\item {} +\item {} \emph{Set optional inputs} Note that the user should not call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPreconditioner]{\emph{\code{ARKStepSetPreconditioner()}}}} as it will overwrite the preconditioner setup and solve functions. -\item {} +\item {} \emph{Create nonlinear solver object} -\item {} +\item {} \emph{Attach nonlinear solver module} -\item {} +\item {} \emph{Set nonlinear solver optional inputs} -\item {} +\item {} \emph{Specify rootfinding problem} -\item {} +\item {} \emph{Advance solution in time} -\item {} +\item {} Get optional outputs Additional optional outputs associated with ARKBANDPRE are @@ -11876,13 +11926,13 @@ \subsubsection{ARKBANDPRE usage} {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetWorkSpace]{\emph{\code{ARKBandPrecGetWorkSpace()}}}} and {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetNumRhsEvals]{\emph{\code{ARKBandPrecGetNumRhsEvals()}}}}. -\item {} +\item {} \emph{Deallocate memory for solution vector} -\item {} +\item {} \emph{Free solver memory} -\item {} +\item {} \emph{Free linear solver memory} \end{enumerate} @@ -11900,34 +11950,34 @@ \subsubsection{ARKBANDPRE user-callable functions} allocates required (internal) memory for it. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{N} -- problem dimension (size of ODE system). -\item {} +\item {} \emph{mu} -- upper half-bandwidth of the Jacobian approximation. -\item {} +\item {} \emph{ml} -- lower half-bandwidth of the Jacobian approximation. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value -\item {} +\item {} \emph{ARKLS\_MEM\_FAIL} if a memory allocation request failed \end{itemize} @@ -11950,29 +12000,29 @@ \subsubsection{ARKBANDPRE user-callable functions} workspaces. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lenrwLS} -- the number of \code{realtype} values in the ARKBANDPRE workspace. -\item {} +\item {} \emph{leniwLS} -- the number of integer values in the ARKBANDPRE workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_PMEM\_NULL} if the preconditioner memory is \code{NULL} \end{itemize} @@ -11999,25 +12049,25 @@ \subsubsection{ARKBANDPRE user-callable functions} preconditioner setup function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{nfevalsBP} -- number of calls to \(f^I\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_PMEM\_NULL} if the preconditioner memory is \code{NULL} \end{itemize} @@ -12154,19 +12204,19 @@ \subsubsection{ARKBBDPRE user-supplied functions} fills the vector \emph{glocal} as a function of \emph{t} and \emph{y}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{Nlocal} -- the local vector length. -\item {} +\item {} \emph{t} -- the value of the independent variable. -\item {} +\item {} \emph{y} -- the value of the dependent variable vector on this process. -\item {} +\item {} \emph{glocal} -- the output vector of \(g(t,y)\) on this process. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -12199,16 +12249,16 @@ \subsubsection{ARKBBDPRE user-supplied functions} above, using the input vector \emph{y}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{Nlocal} -- the local vector length. -\item {} +\item {} \emph{t} -- the value of the independent variable. -\item {} +\item {} \emph{y} -- the value of the dependent variable vector on this process. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter passed to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}. @@ -12249,34 +12299,34 @@ \subsubsection{ARKBBDPRE usage} that are unchanged from the skeleton program presented in {\hyperref[ARKStep_c_interface/Skeleton:arkstep-cinterface-skeleton]{\emph{\DUspan{}{A skeleton of the user's main program}}}} are \emph{italicized}. \begin{enumerate} -\item {} +\item {} \emph{Initialize MPI} -\item {} +\item {} \emph{Set problem dimensions} -\item {} +\item {} \emph{Set vector of initial values} -\item {} +\item {} \emph{Create ARKStep object} -\item {} +\item {} \emph{Specify integration tolerances} -\item {} +\item {} Create iterative linear solver object When creating the iterative linear solver object, specify the type of preconditioning (\code{PREC\_LEFT} or \code{PREC\_RIGHT}) to use. -\item {} +\item {} \emph{Set linear solver optional inputs} -\item {} +\item {} \emph{Attach linear solver module} -\item {} +\item {} Initialize the ARKBBDPRE preconditioner module Specify the upper and lower half-bandwidths for computation @@ -12290,29 +12340,29 @@ \subsubsection{ARKBBDPRE usage} two user-supplied functions of type {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKLocalFn]{\emph{\code{ARKLocalFn()}}}} and {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKCommFn]{\emph{\code{ARKCommFn()}}}} described above, respectively. -\item {} +\item {} \emph{Set optional inputs} Note that the user should not call {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPreconditioner]{\emph{\code{ARKStepSetPreconditioner()}}}} as it will overwrite the preconditioner setup and solve functions. -\item {} +\item {} \emph{Create nonlinear solver object} -\item {} +\item {} \emph{Attach nonlinear solver module} -\item {} +\item {} \emph{Set nonlinear solver optional inputs} -\item {} +\item {} \emph{Specify rootfinding problem} -\item {} +\item {} \emph{Advance solution in time} -\item {} +\item {} \emph{Get optional outputs} Additional optional outputs associated with ARKBBDPRE are @@ -12320,16 +12370,16 @@ \subsubsection{ARKBBDPRE usage} {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecGetWorkSpace]{\emph{\code{ARKBBDPrecGetWorkSpace()}}}} and {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecGetNumGfnEvals]{\emph{\code{ARKBBDPrecGetNumGfnEvals()}}}}. -\item {} +\item {} \emph{Deallocate memory for solution vector} -\item {} +\item {} \emph{Free solver memory} -\item {} +\item {} \emph{Free linear solver memory} -\item {} +\item {} \emph{Finalize MPI} \end{enumerate} @@ -12347,39 +12397,39 @@ \subsubsection{ARKBBDPRE user-callable functions} ARKBBDPRE preconditioner. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{Nlocal} -- local vector length. -\item {} +\item {} \emph{mudq} -- upper half-bandwidth to be used in the difference quotient Jacobian approximation. -\item {} +\item {} \emph{mldq} -- lower half-bandwidth to be used in the difference quotient Jacobian approximation. -\item {} +\item {} \emph{mukeep} -- upper half-bandwidth of the retained banded approximate Jacobian block. -\item {} +\item {} \emph{mlkeep} -- lower half-bandwidth of the retained banded approximate Jacobian block. -\item {} +\item {} \emph{dqrely} -- the relative increment in components of \emph{y} used in the difference quotient approximations. The default is \emph{dqrely} = \(\sqrt{\text{unit roundoff}}\), which can be specified by passing \emph{dqrely} = 0.0. -\item {} +\item {} \emph{gloc} -- the name of the C function (of type {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKLocalFn]{\emph{\code{ARKLocalFn()}}}}) which computes the approximation \(g(t,y) \approx f^I(t,y)\). -\item {} +\item {} \emph{cfn} -- the name of the C function (of type {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKCommFn]{\emph{\code{ARKCommFn()}}}}) which performs all inter-process communication required for the computation of \(g(t,y)\). @@ -12387,19 +12437,19 @@ \subsubsection{ARKBBDPRE user-callable functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_ILL\_INPUT} if an input has an illegal value -\item {} +\item {} \emph{ARKLS\_MEM\_FAIL} if a memory allocation request failed \end{itemize} @@ -12446,18 +12496,18 @@ \subsubsection{ARKBBDPRE user-callable functions} Re-initializes the ARKBBDPRE preconditioner module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{mudq} -- upper half-bandwidth to be used in the difference quotient Jacobian approximation. -\item {} +\item {} \emph{mldq} -- lower half-bandwidth to be used in the difference quotient Jacobian approximation. -\item {} +\item {} \emph{dqrely} -- the relative increment in components of \emph{y} used in the difference quotient approximations. The default is \emph{dqrely} = \(\sqrt{\text{unit roundoff}}\), which can be specified by @@ -12466,16 +12516,16 @@ \subsubsection{ARKBBDPRE user-callable functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_PMEM\_NULL} if the preconditioner memory is \code{NULL} \end{itemize} @@ -12499,29 +12549,29 @@ \subsubsection{ARKBBDPRE user-callable functions} integer workspace sizes. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{lenrwBBDP} -- the number of \code{realtype} values in the ARKBBDPRE workspace. -\item {} +\item {} \emph{leniwBBDP} -- the number of integer values in the ARKBBDPRE workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_PMEM\_NULL} if the preconditioner memory is \code{NULL} \end{itemize} @@ -12548,26 +12598,26 @@ \subsubsection{ARKBBDPRE user-callable functions} preconditioner setup function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{ngevalsBBDP} -- the number of calls made to the user-supplied \emph{gloc} function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKLS\_SUCCESS} if no errors occurred -\item {} +\item {} \emph{ARKLS\_MEM\_NULL} if the ARKStep memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_LMEM\_NULL} if the linear solver memory is \code{NULL} -\item {} +\item {} \emph{ARKLS\_PMEM\_NULL} if the preconditioner memory is \code{NULL} \end{itemize} @@ -12619,10 +12669,10 @@ \section{Access to library and header files} appropriate locations for the library and header files required by ARKode. The relevant library files are \begin{itemize} -\item {} +\item {} \code{libdir/libsundials\_arkode.lib}, -\item {} +\item {} \code{libdir/libsundials\_nvec*.lib}, \end{itemize} @@ -12631,13 +12681,13 @@ \section{Access to library and header files} libraries and \code{.a} for static libraries. The relevant header files are located in the subdirectories \begin{itemize} -\item {} +\item {} \code{incdir/include/arkode} -\item {} +\item {} \code{incdir/include/sundials} -\item {} +\item {} \code{incdir/include/nvector} \end{itemize} @@ -12736,7 +12786,7 @@ \section{Header Files} files so that various macros and data types can be used. The header file that is always required is: \begin{itemize} -\item {} +\item {} \code{arkode/arkode\_erkstep.h}, the main header file for the ERKStep time-stepping module, which defines the several types and various constants, includes function prototypes, and includes the shared @@ -12768,14 +12818,14 @@ \section{A skeleton of the user's main program} referenced. \index{User main program}\begin{enumerate} -\item {} +\item {} Initialize parallel or multi-threaded environment, if appropriate. For example, call \code{MPI\_Init} to initialize MPI if used, or set \code{num\_threads}, the number of threads to use within the threaded vector functions, if used. -\item {} +\item {} Set problem dimensions, etc. This generally includes the problem size, \code{N}, and may include @@ -12786,7 +12836,7 @@ \section{A skeleton of the user's main program} \code{sunindextype}. \end{notice} -\item {} +\item {} Set vector of initial values To set the vector \code{y0} of initial values, use the appropriate @@ -12855,7 +12905,7 @@ \section{A skeleton of the user's main program} and device when instantiated. See the sections {\hyperref[nvectors/NVector_CUDA:nvectors-cuda]{\emph{\DUspan{}{The NVECTOR\_CUDA Module}}}} and {\hyperref[nvectors/NVector_RAJA:nvectors-raja]{\emph{\DUspan{}{The NVECTOR\_RAJA Module}}}} for details. -\item {} +\item {} Create ERKStep object Call \code{arkode\_mem = ERKStepCreate(...)} to create the ERKStep memory @@ -12863,7 +12913,7 @@ \section{A skeleton of the user's main program} this memory structure. See the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-initialization]{\emph{\DUspan{}{ERKStep initialization and deallocation functions}}}} for details. -\item {} +\item {} Specify integration tolerances Call {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSStolerances]{\emph{\code{ERKStepSStolerances()}}}} or @@ -12875,14 +12925,14 @@ \section{A skeleton of the user's main program} evaluating WRMS vector norms. See the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-tolerances]{\emph{\DUspan{}{ERKStep tolerance specification functions}}}} for details. -\item {} +\item {} Set optional inputs Call \code{ERKStepSet*} functions to change any optional inputs that control the behavior of ERKStep from their default values. See the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for details. -\item {} +\item {} Specify rootfinding problem Optionally, call {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepRootInit]{\emph{\code{ERKStepRootInit()}}}} to initialize a rootfinding @@ -12891,7 +12941,7 @@ \section{A skeleton of the user's main program} the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for relevant optional input calls. -\item {} +\item {} Advance solution in time For each point at which output is desired, call @@ -12905,13 +12955,13 @@ \section{A skeleton of the user's main program} \(y(t_\text{out})\). See the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-integration]{\emph{\DUspan{}{ERKStep solver function}}}} for details. -\item {} +\item {} Get optional outputs Call \code{ERKStepGet*} functions to obtain optional output. See the section {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}} for details. -\item {} +\item {} Deallocate memory for solution vector Upon completion of the integration, deallocate memory for the @@ -12922,13 +12972,13 @@ \section{A skeleton of the user's main program} \PYG{n}{N\PYGZus{}VDestroy}\PYG{p}{(}\PYG{n}{y}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Free solver memory Call \code{ERKStepFree(\&arkode\_mem)} to free the memory allocated for the ERKStep module. -\item {} +\item {} Finalize MPI, if used Call \code{MPI\_Finalize} to terminate MPI. @@ -12964,15 +13014,15 @@ \subsection{ERKStep initialization and deallocation functions} be solved using the ERKStep time-stepping module in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{f} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the right-hand side function in \(\dot{y} = f(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). \end{itemize} @@ -12994,7 +13044,7 @@ \subsection{ERKStep initialization and deallocation functions} {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepCreate]{\emph{\code{ERKStepCreate()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. \end{itemize} @@ -13046,28 +13096,28 @@ \subsection{ERKStep tolerance specification functions} This function specifies scalar relative and absolute tolerances. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{reltol} -- scalar relative tolerance. -\item {} +\item {} \emph{abstol} -- scalar absolute tolerance. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ERKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -13085,29 +13135,29 @@ \subsection{ERKStep tolerance specification functions} each vector component). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{reltol} -- scalar relative tolerance. -\item {} +\item {} \emph{abstol} -- vector containing the absolute tolerances for each solution component. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ERKStep memory was not allocated by the time-stepping module -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value (e.g. a negative tolerance). \end{itemize} @@ -13119,28 +13169,28 @@ \subsection{ERKStep tolerance specification functions} \index{ERKStepWFtolerances (C function)} \begin{fulllineitems} -\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepWFtolerances}\pysiglinewithargsret{int \bfcode{ERKStepWFtolerances}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{ARKEwtFn}}}\emph{ efun}}{} +\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepWFtolerances}\pysiglinewithargsret{int \bfcode{ERKStepWFtolerances}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{ARKEwtFn}}}\emph{ efun}}{} This function specifies a user-supplied function \emph{efun} to compute the error weight vector \code{ewt}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} -\emph{efun} -- the name of the function (of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}}) +\item {} +\emph{efun} -- the name of the function (of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}}) that implements the error weight vector computation. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if the ERKStep memory was not allocated by the time-stepping module \end{itemize} @@ -13157,7 +13207,7 @@ \subsubsection{General advice on the choice of tolerances} \code{reltol} and \code{abstol} are a concern. The following pieces of advice are relevant. \begin{enumerate} -\item {} +\item {} The scalar relative tolerance \code{reltol} is to be set to control relative errors. So a value of \(10^{-4}\) means that errors are controlled to .01\%. We do not recommend using \code{reltol} larger @@ -13165,7 +13215,7 @@ \subsubsection{General advice on the choice of tolerances} small that it is comparable to the unit roundoff of the machine arithmetic (generally around \(10^{-15}\) for double-precision). -\item {} +\item {} The absolute tolerances \code{abstol} (whether scalar or vector) need to be set to control absolute errors when any components of the solution vector \(y\) may be so small that pure relative error @@ -13185,7 +13235,7 @@ \subsubsection{General advice on the choice of tolerances} problem-dependent. The user or modeler hopefully has some idea as to what those noise levels are. -\item {} +\item {} Finally, it is important to pick all the tolerance values conservatively, because they control the error committed on each individual step. The final (global) errors are an accumulation of @@ -13210,14 +13260,14 @@ \subsubsection{Advice on controlling nonphysical negative values} that violates a constraint may cause a simulation to halt. For both of these scenarios the following pieces of advice are relevant. \begin{enumerate} -\item {} +\item {} The best way to control the size of unwanted negative computed values is with tighter absolute tolerances. Again this requires some knowledge of the noise level of these components, which may or may not be different for different components. Some experimentation may be needed. -\item {} +\item {} If output plots or tables are being generated, and it is important to avoid having negative numbers appear there (for the sake of avoiding a long explanation of them, if nothing else), then @@ -13227,7 +13277,7 @@ \subsubsection{Advice on controlling nonphysical negative values} magnitude comparable to \code{abstol} or less, is equivalent to zero as far as the computation is concerned. -\item {} +\item {} The user's right-hand side routine \(f\) should never change a negative value in the solution vector \(y\) to a non-negative value in attempt to ``fix'' this problem, @@ -13238,7 +13288,7 @@ \subsubsection{Advice on controlling nonphysical negative values} (not in the input \(y\) vector) for the purposes of computing \(f(t, y)\). -\item {} +\item {} Positivity and non-negativity constraints on components can be enforced by use of the recoverable error return feature in the user-supplied right-hand side function, \(f\). When a @@ -13270,29 +13320,29 @@ \subsection{Rootfinding initialization function} {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepCreate]{\emph{\code{ERKStepCreate()}}}}, and before {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepEvolve]{\emph{\code{ERKStepEvolve()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{nrtfn} -- number of functions \(g_i\), an integer \(\ge\) 0. -\item {} +\item {} \emph{g} -- name of user-supplied function, of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRootFn]{\emph{\code{ARKRootFn()}}}}, defining the functions \(g_i\) whose roots are sought. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if \emph{nrtfn} is greater than zero but \emph{g} = \code{NULL}. \end{itemize} @@ -13327,19 +13377,19 @@ \subsection{ERKStep solver function} Integrates the ODE over an interval in \(t\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{tout} -- the next time at which a computed solution is desired. -\item {} +\item {} \emph{yout} -- the computed solution vector. -\item {} +\item {} \emph{tret} -- the time corresponding to \emph{yout} (output). -\item {} +\item {} \emph{itask} -- a flag indicating the job of the solver for the next user step. @@ -13363,60 +13413,60 @@ \subsection{ERKStep solver function} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful. -\item {} +\item {} \emph{ARK\_ROOT\_RETURN} if {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepEvolve]{\emph{\code{ERKStepEvolve()}}}} succeeded, and found one or more roots. If the number of root functions, \emph{nrtfn}, is greater than 1, call {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetRootInfo]{\emph{\code{ERKStepGetRootInfo()}}}} to see which \(g_i\) were found to have a root at (\emph{*tret}). -\item {} +\item {} \emph{ARK\_TSTOP\_RETURN} if {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepEvolve]{\emph{\code{ERKStepEvolve()}}}} succeeded and returned at \emph{tstop}. -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the \emph{arkode\_mem} argument was \code{NULL}. -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if one of the inputs to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepEvolve]{\emph{\code{ERKStepEvolve()}}}} is illegal, or some other input to the solver was either illegal or missing. Details will be provided in the error message. Typical causes of this failure: \begin{enumerate} -\item {} +\item {} A component of the error weight vector became zero during internal time-stepping. -\item {} +\item {} A root of one of the root functions was found both at a point \(t\) and also very near \(t\). -\item {} +\item {} The initial condition violates the inequality constraints. \end{enumerate} -\item {} +\item {} \emph{ARK\_TOO\_MUCH\_WORK} if the solver took \emph{mxstep} internal steps but could not reach \emph{tout}. The default value for \emph{mxstep} is \emph{MXSTEP\_DEFAULT = 500}. -\item {} +\item {} \emph{ARK\_TOO\_MUCH\_ACC} if the solver could not satisfy the accuracy demanded by the user for some internal step. -\item {} +\item {} \emph{ARK\_ERR\_FAILURE} if error test failures occurred either too many times (\emph{ark\_maxnef}) during one internal time step or occurred with \(|h| = h_{min}\). -\item {} +\item {} \emph{ARK\_VECTOROP\_ERR} a vector operation error occured. \end{itemize} @@ -13465,13 +13515,13 @@ \subsection{Optional input functions} The optional inputs are grouped into the following categories: \begin{itemize} -\item {} +\item {} General ERKStep options ({\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepinputtable]{\emph{\DUspan{}{Optional inputs for ERKStep}}}}), -\item {} +\item {} IVP method solver options ({\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepmethodinputtable]{\emph{\DUspan{}{Optional inputs for IVP method selection}}}}), -\item {} +\item {} Step adaptivity solver options ({\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepadaptivityinputtable]{\emph{\DUspan{}{Optional inputs for time step adaptivity}}}}), \end{itemize} @@ -13490,123 +13540,123 @@ \subsubsection{Optional inputs for ERKStep} \label{ERKStep_c_interface/User_callable:optional-inputs-for-erkstep}\label{ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepinputtable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Return ERKStep solver parameters to their defaults - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetDefaults]{\emph{\code{ERKStepSetDefaults()}}}} - & + & internal \\ \hline Set dense output order - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetDenseOrder]{\emph{\code{ERKStepSetDenseOrder()}}}} - & + & 3 \\ \hline Supply a pointer to a diagnostics output file - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetDiagnostics]{\emph{\code{ERKStepSetDiagnostics()}}}} - & + & \code{NULL} \\ \hline Supply a pointer to an error output file - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetErrFile]{\emph{\code{ERKStepSetErrFile()}}}} - & + & \code{stderr} \\ \hline Supply a custom error handler function - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetErrHandlerFn]{\emph{\code{ERKStepSetErrHandlerFn()}}}} - & + & internal fn \\ \hline Disable time step adaptivity (fixed-step mode) - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetFixedStep]{\emph{\code{ERKStepSetFixedStep()}}}} - & + & disabled \\ \hline Supply an initial step size to attempt - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetInitStep]{\emph{\code{ERKStepSetInitStep()}}}} - & + & estimated \\ \hline Maximum no. of warnings for \(t_n+h = t_n\) - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxHnilWarns]{\emph{\code{ERKStepSetMaxHnilWarns()}}}} - & + & 10 \\ \hline Maximum no. of internal steps before \emph{tout} - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxNumSteps]{\emph{\code{ERKStepSetMaxNumSteps()}}}} - & + & 500 \\ \hline Maximum absolute step size - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxStep]{\emph{\code{ERKStepSetMaxStep()}}}} - & + & \(\infty\) \\ \hline Minimum absolute step size - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMinStep]{\emph{\code{ERKStepSetMinStep()}}}} - & + & 0.0 \\ \hline Set a value for \(t_{stop}\) - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetStopTime]{\emph{\code{ERKStepSetStopTime()}}}} - & + & \(\infty\) \\ \hline Supply a pointer for user data - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetUserData]{\emph{\code{ERKStepSetUserData()}}}} - & + & \code{NULL} \\ \hline Maximum no. of ERKStep error test failures - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxErrTestFails]{\emph{\code{ERKStepSetMaxErrTestFails()}}}} - & + & 7 \\ \hline Set inequality constraints on solution - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetConstraints]{\emph{\code{ERKStepSetConstraints()}}}} - & + & \code{NULL} \\ \hline Set max number of constraint failures - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxNumConstrFails]{\emph{\code{ERKStepSetMaxNumConstrFails()}}}} - & + & 10 \\ \hline\end{tabulary} @@ -13619,19 +13669,19 @@ \subsubsection{Optional inputs for ERKStep} default values. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13654,22 +13704,22 @@ \subsubsection{Optional inputs for ERKStep} used for dense output (i.e. interpolation of solution output values). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{dord} -- requested polynomial order of accuracy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13689,22 +13739,22 @@ \subsubsection{Optional inputs for ERKStep} all ERKStep step adaptivity and solver information is written. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{diagfp} -- pointer to the diagnostics output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13731,22 +13781,22 @@ \subsubsection{Optional inputs for ERKStep} function is used. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{errfp} -- pointer to the output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13773,26 +13823,26 @@ \subsubsection{Optional inputs for ERKStep} in handling error messages. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{ehfun} -- name of user-supplied error handler function. -\item {} +\item {} \emph{eh\_data} -- pointer to user data passed to \emph{ehfun} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13812,22 +13862,22 @@ \subsubsection{Optional inputs for ERKStep} fixed time step size to use for all internal steps. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hfixed} -- value of the fixed step size to use. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13881,22 +13931,22 @@ \subsubsection{Optional inputs for ERKStep} initialization or re-initialization. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hin} -- value of the initial step to be attempted \((\ne 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13921,22 +13971,22 @@ \subsubsection{Optional inputs for ERKStep} ERKStep will instead return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{mxhnil} -- maximum allowed number of warning messages \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13959,22 +14009,22 @@ \subsubsection{Optional inputs for ERKStep} will return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{mxsteps} -- maximum allowed number of internal steps. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -13995,22 +14045,22 @@ \subsubsection{Optional inputs for ERKStep} Specifies the upper bound on the magnitude of the time step size. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hmax} -- maximum absolute value of the time step size \((\ge 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14028,22 +14078,22 @@ \subsubsection{Optional inputs for ERKStep} Specifies the lower bound on the magnitude of the time step size. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hmin} -- minimum absolute value of the time step size \((\ge 0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14062,22 +14112,22 @@ \subsubsection{Optional inputs for ERKStep} \(t\) past which the solution is not to proceed. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{tstop} -- stopping time for the integrator. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14096,22 +14146,22 @@ \subsubsection{Optional inputs for ERKStep} attaches it to the main ERKStep memory block. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{user\_data} -- pointer to the user data. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14132,22 +14182,22 @@ \subsubsection{Optional inputs for ERKStep} permitted in attempting one step, before returning with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{maxnef} -- maximum allowed number of error test failures \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14167,25 +14217,25 @@ \subsubsection{Optional inputs for ERKStep} solution vector \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{constraints} -- vector of constraint flags. If \code{constraints{[}i{]}} is \begin{itemize} -\item {} +\item {} 0.0 then no constraint is imposed on \(y_i\) -\item {} +\item {} 1.0 then \(y_i\) will be constrained to be \(y_i \geq 0.0\) -\item {} +\item {} -1.0 then \(y_i\) will be constrained to be \(y_i \leq 0.0\) -\item {} +\item {} 2.0 then \(y_i\) will be constrained to be \(y_i > 0.0\) -\item {} +\item {} -2.0 then \(y_i\) will be constrained to be \(y_i < 0.0\) \end{itemize} @@ -14193,13 +14243,13 @@ \subsubsection{Optional inputs for ERKStep} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if the constraints vector contains illegal values \end{itemize} @@ -14221,19 +14271,19 @@ \subsubsection{Optional inputs for ERKStep} will return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{maxfails} -- maximum allowed number of constrain failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} \end{itemize} @@ -14251,32 +14301,32 @@ \subsubsection{Optional inputs for IVP method selection} \label{ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepmethodinputtable}\label{ERKStep_c_interface/User_callable:optional-inputs-for-ivp-method-selection} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Set integrator method order - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetOrder]{\emph{\code{ERKStepSetOrder()}}}} - & + & 4 \\ \hline Set explicit RK table - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetTable]{\emph{\code{ERKStepSetTable()}}}} - & + & internal \\ \hline Specify explicit RK table number - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetTableNum]{\emph{\code{ERKStepSetTableNum()}}}} - & + & internal \\ \hline\end{tabulary} @@ -14288,22 +14338,22 @@ \subsubsection{Optional inputs for IVP method selection} Specifies the order of accuracy for the ERK integration method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{ord} -- requested order of accuracy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14326,22 +14376,22 @@ \subsubsection{Optional inputs for IVP method selection} Specifies a customized Butcher table for the ERK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{B} -- the Butcher table for the explicit RK method. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14373,22 +14423,22 @@ \subsubsection{Optional inputs for IVP method selection} Indicates to use a specific built-in Butcher table for the ERK method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{etable} -- index of the Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14411,88 +14461,88 @@ \subsubsection{Optional inputs for time step adaptivity} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Set a custom time step adaptivity function - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetAdaptivityFn]{\emph{\code{ERKStepSetAdaptivityFn()}}}} - & + & internal \\ \hline Choose an existing time step adaptivity method - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetAdaptivityMethod]{\emph{\code{ERKStepSetAdaptivityMethod()}}}} - & + & 0 \\ \hline Explicit stability safety factor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetCFLFraction]{\emph{\code{ERKStepSetCFLFraction()}}}} - & + & 0.5 \\ \hline Time step error bias factor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetErrorBias]{\emph{\code{ERKStepSetErrorBias()}}}} - & + & 1.5 \\ \hline Bounds determining no change in step size - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetFixedStepBounds]{\emph{\code{ERKStepSetFixedStepBounds()}}}} - & + & 1.0 1.5 \\ \hline Maximum step growth factor on error test fail - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxEFailGrowth]{\emph{\code{ERKStepSetMaxEFailGrowth()}}}} - & + & 0.3 \\ \hline Maximum first step growth factor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxFirstGrowth]{\emph{\code{ERKStepSetMaxFirstGrowth()}}}} - & + & 10000.0 \\ \hline Maximum general step growth factor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxGrowth]{\emph{\code{ERKStepSetMaxGrowth()}}}} - & + & 20.0 \\ \hline Time step safety factor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetSafetyFactor]{\emph{\code{ERKStepSetSafetyFactor()}}}} - & + & 0.96 \\ \hline Error fails before MaxEFailGrowth takes effect - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetSmallNumEFails]{\emph{\code{ERKStepSetSmallNumEFails()}}}} - & + & 2 \\ \hline Explicit stability function - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetStabilityFn]{\emph{\code{ERKStepSetStabilityFn()}}}} - & + & none \\ \hline\end{tabulary} @@ -14500,30 +14550,30 @@ \subsubsection{Optional inputs for time step adaptivity} \index{ERKStepSetAdaptivityFn (C function)} \begin{fulllineitems} -\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepSetAdaptivityFn}\pysiglinewithargsret{int \bfcode{ERKStepSetAdaptivityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{ARKAdaptFn}}}\emph{ hfun}, void*\emph{ h\_data}}{} +\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepSetAdaptivityFn}\pysiglinewithargsret{int \bfcode{ERKStepSetAdaptivityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{ARKAdaptFn}}}\emph{ hfun}, void*\emph{ h\_data}}{} Sets a user-supplied time-step adaptivity function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hfun} -- name of user-supplied adaptivity function. -\item {} +\item {} \emph{h\_data} -- pointer to user data passed to \emph{hfun} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14543,44 +14593,44 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the method (and associated parameters) used for time step adaptivity. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{imethod} -- accuracy-based adaptivity method choice (0 \(\le\) \emph{imethod} \(\le\) 5): 0 is PID, 1 is PI, 2 is I, 3 is explicit Gustafsson, 4 is implicit Gustafsson, and 5 is the ImEx Gustafsson. -\item {} +\item {} \emph{idefault} -- flag denoting whether to use default adaptivity parameters (1), or that they will be supplied in the \emph{adapt\_params} argument (0). -\item {} +\item {} \emph{pq} -- flag denoting whether to use the embedding order of accuracy \emph{p} (0) or the method order of accuracy \emph{q} (1) within the adaptivity algorithm. \emph{p} is the default. -\item {} +\item {} \emph{adapt\_params{[}0{]}} -- \(k_1\) parameter within accuracy-based adaptivity algorithms. -\item {} +\item {} \emph{adapt\_params{[}1{]}} -- \(k_2\) parameter within accuracy-based adaptivity algorithms. -\item {} +\item {} \emph{adapt\_params{[}2{]}} -- \(k_3\) parameter within accuracy-based adaptivity algorithms. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14601,22 +14651,22 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the fraction of the estimated explicitly stable step to use. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{cfl\_frac} -- maximum allowed fraction of explicitly stable step (default is 0.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14636,23 +14686,23 @@ \subsubsection{Optional inputs for time step adaptivity} accuracy-based adaptivity strategies. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{bias} -- bias applied to error in accuracy-based time step estimation (default is 1.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14670,25 +14720,25 @@ \subsubsection{Optional inputs for time step adaptivity} Specifies the step growth interval in which the step size will remain unchanged. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{lb} -- lower bound on window to leave step size fixed (default is 1.0). -\item {} +\item {} \emph{ub} -- upper bound on window to leave step size fixed (default is 1.5). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14707,22 +14757,22 @@ \subsubsection{Optional inputs for time step adaptivity} accuracy-based error failures in the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{etamxf} -- time step reduction factor on multiple error fails (default is 0.3). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14741,23 +14791,23 @@ \subsubsection{Optional inputs for time step adaptivity} first integration step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{etamx1} -- maximum allowed growth factor after the first time step (default is 10000.0). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14776,22 +14826,22 @@ \subsubsection{Optional inputs for time step adaptivity} steps in the integration process. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{growth} -- maximum allowed growth factor between consecutive time steps (default is 20.0). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14811,22 +14861,22 @@ \subsubsection{Optional inputs for time step adaptivity} estimated step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{safety} -- safety factor applied to accuracy-based time step (default is 0.96). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14847,22 +14897,22 @@ \subsubsection{Optional inputs for time step adaptivity} {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetMaxEFailGrowth]{\emph{\code{ERKStepSetMaxEFailGrowth()}}}} is applied. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{small\_nef} -- bound to determine `multiple' for \emph{etamxf} (default is 2). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14876,31 +14926,31 @@ \subsubsection{Optional inputs for time step adaptivity} \index{ERKStepSetStabilityFn (C function)} \begin{fulllineitems} -\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepSetStabilityFn}\pysiglinewithargsret{int \bfcode{ERKStepSetStabilityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{ARKExpStabFn}}}\emph{ EStab}, void*\emph{ estab\_data}}{} +\phantomsection\label{ERKStep_c_interface/User_callable:c.ERKStepSetStabilityFn}\pysiglinewithargsret{int \bfcode{ERKStepSetStabilityFn}}{void*\emph{ arkode\_mem}, {\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{ARKExpStabFn}}}\emph{ EStab}, void*\emph{ estab\_data}}{} Sets the problem-dependent function to estimate a stable time step size for the explicit portion of the ODE system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{EStab} -- name of user-supplied stability function. -\item {} +\item {} \emph{estab\_data} -- pointer to user data passed to \emph{EStab} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14926,25 +14976,25 @@ \subsubsection{Rootfinding optional input functions} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Direction of zero-crossings to monitor - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetRootDirection]{\emph{\code{ERKStepSetRootDirection()}}}} - & + & both \\ \hline Disable inactive root warnings - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetNoInactiveRootWarn]{\emph{\code{ERKStepSetNoInactiveRootWarn()}}}} - & + & enabled \\ \hline\end{tabulary} @@ -14956,10 +15006,10 @@ \subsubsection{Rootfinding optional input functions} Specifies the direction of zero-crossings to be located and returned. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{rootdir} -- state array of length \emph{nrtfn}, the number of root functions \(g_i\) (the value of \emph{nrtfn} was supplied in the call to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepRootInit]{\emph{\code{ERKStepRootInit()}}}}). If \code{rootdir{[}i{]} == @@ -14971,13 +15021,13 @@ \subsubsection{Rootfinding optional input functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -14996,16 +15046,16 @@ \subsubsection{Rootfinding optional input functions} to be identically zero at the beginning of the integration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} \end{itemize} @@ -15053,35 +15103,35 @@ \subsection{Interpolated output function} range \{0,...,*dord*\}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{t} -- the value of the independent variable at which the derivative is to be evaluated. -\item {} +\item {} \emph{k} -- the derivative order requested. -\item {} +\item {} \emph{dky} -- output vector (must be allocated by the user). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_BAD\_K} if \emph{k} is not in the range \{0,...,*dord*\}. -\item {} +\item {} \emph{ARK\_BAD\_T} if \emph{t} is not in the interval \([t_n-h_n, t_n]\) -\item {} +\item {} \emph{ARK\_BAD\_DKY} if the \emph{dky} vector was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory is \code{NULL} \end{itemize} @@ -15104,19 +15154,19 @@ \subsection{Optional output functions} ERKStep provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups: \begin{enumerate} -\item {} +\item {} SUNDIALS version information accessor routines are in the subsection {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-sunversioninfo]{\emph{\DUspan{}{SUNDIALS version information}}}}, -\item {} +\item {} General ERKStep output routines are in the subsection {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepmainoutputs]{\emph{\DUspan{}{Main solver optional output functions}}}}, -\item {} +\item {} Output routines regarding root-finding results are in the subsection {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erksteprootoutputs]{\emph{\DUspan{}{Rootfinding optional output functions}}}}, -\item {} +\item {} General usability routines (e.g. to print the current ERKStep parameters, or output the current Butcher table) are in the subsection {\hyperref[ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepextraoutputs]{\emph{\DUspan{}{General usability functions}}}}. @@ -15129,13 +15179,13 @@ \subsection{Optional output functions} very useful in determining the efficiency of various methods inside ERKStep. For example: \begin{itemize} -\item {} +\item {} The counters \emph{nsteps} and \emph{nf\_evals} provide a rough measure of the overall cost of a given run, and can be compared between runs with different solver options to suggest which set of options is the most efficient. -\item {} +\item {} The ratio \emph{nsteps/step\_attempts} can measure the quality of the time step adaptivity algorithm, since a poor algorithm will result in more failed steps, and hence a lower ratio. @@ -15159,19 +15209,19 @@ \subsubsection{SUNDIALS version information} This routine fills a string with SUNDIALS version information. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{version} -- character array to hold the SUNDIALS version information. -\item {} +\item {} \emph{len} -- allocated length of the \emph{version} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS version \end{itemize} @@ -15192,28 +15242,28 @@ \subsubsection{SUNDIALS version information} release label if applicable. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{major} -- SUNDIALS release major version number. -\item {} +\item {} \emph{minor} -- SUNDIALS release minor version number. -\item {} +\item {} \emph{patch} -- SUNDIALS release patch version number. -\item {} +\item {} \emph{label} -- string to hold the SUNDIALS release label. -\item {} +\item {} \emph{len} -- allocated length of the \emph{label} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS label \end{itemize} @@ -15232,104 +15282,104 @@ \subsubsection{Main solver optional output functions} \label{ERKStep_c_interface/User_callable:erkstep-cinterface-erkstepmainoutputs}\label{ERKStep_c_interface/User_callable:main-solver-optional-output-functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Size of ERKStep real and integer workspaces - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetWorkSpace]{\emph{\code{ERKStepGetWorkSpace()}}}} \\ \hline Cumulative number of internal steps - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumSteps]{\emph{\code{ERKStepGetNumSteps()}}}} \\ \hline Actual initial time step size used - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetActualInitStep]{\emph{\code{ERKStepGetActualInitStep()}}}} \\ \hline Step size used for the last successful step - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetLastStep]{\emph{\code{ERKStepGetLastStep()}}}} \\ \hline Step size to be attempted on the next step - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetCurrentStep]{\emph{\code{ERKStepGetCurrentStep()}}}} \\ \hline Current internal time reached by the solver - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetCurrentTime]{\emph{\code{ERKStepGetCurrentTime()}}}} \\ \hline Suggested factor for tolerance scaling - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetTolScaleFactor]{\emph{\code{ERKStepGetTolScaleFactor()}}}} \\ \hline Error weight vector for state variables - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetErrWeights]{\emph{\code{ERKStepGetErrWeights()}}}} \\ \hline Single accessor to many statistics at once - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetStepStats]{\emph{\code{ERKStepGetStepStats()}}}} \\ \hline Name of constant associated with a return flag - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetReturnFlagName]{\emph{\code{ERKStepGetReturnFlagName()}}}} \\ \hline No. of explicit stability-limited steps - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumExpSteps]{\emph{\code{ERKStepGetNumExpSteps()}}}} \\ \hline No. of accuracy-limited steps - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumAccSteps]{\emph{\code{ERKStepGetNumAccSteps()}}}} \\ \hline No. of attempted steps - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumStepAttempts]{\emph{\code{ERKStepGetNumStepAttempts()}}}} \\ \hline No. of calls to \emph{f} function - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumRhsEvals]{\emph{\code{ERKStepGetNumRhsEvals()}}}} \\ \hline No. of local error test failures that have occurred - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumErrTestFails]{\emph{\code{ERKStepGetNumErrTestFails()}}}} \\ \hline Current ERK Butcher table - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetCurrentButcherTable]{\emph{\code{ERKStepGetCurrentButcherTable()}}}} \\ \hline Estimated local truncation error vector - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetEstLocalErrors]{\emph{\code{ERKStepGetEstLocalErrors()}}}} \\ \hline Single accessor to many statistics at once - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetTimestepperStats]{\emph{\code{ERKStepGetTimestepperStats()}}}} \\ \hline Number of constraint test failures - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumConstrFails]{\emph{\code{ERKStepGetNumConstrFails()}}}} \\ \hline\end{tabulary} @@ -15341,22 +15391,22 @@ \subsubsection{Main solver optional output functions} Returns the ERKStep real and integer workspace sizes. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{lenrw} -- the number of \code{realtype} values in the ERKStep workspace. -\item {} +\item {} \emph{leniw} -- the number of integer values in the ERKStep workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15373,19 +15423,19 @@ \subsubsection{Main solver optional output functions} the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{nsteps} -- number of steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15401,19 +15451,19 @@ \subsubsection{Main solver optional output functions} Returns the value of the integration step size used on the first step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hinused} -- actual value of initial step size. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15437,19 +15487,19 @@ \subsubsection{Main solver optional output functions} internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hlast} -- step size taken on the last internal step. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15465,19 +15515,19 @@ \subsubsection{Main solver optional output functions} Returns the integration step size to be attempted on the next internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{hcur} -- step size to be attempted on the next internal step. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15493,19 +15543,19 @@ \subsubsection{Main solver optional output functions} Returns the current internal time reached by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{tcur} -- current internal time reached. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15523,19 +15573,19 @@ \subsubsection{Main solver optional output functions} requested for some internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{tolsfac} -- suggested scaling factor for user-supplied tolerances. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15551,19 +15601,19 @@ \subsubsection{Main solver optional output functions} Returns the current error weight vector. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{eweight} -- solution error weights at the current time. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15582,31 +15632,31 @@ \subsubsection{Main solver optional output functions} Returns many of the most useful optional outputs in a single call. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{nsteps} -- number of steps taken in the solver. -\item {} +\item {} \emph{hinused} -- actual value of initial step size. -\item {} +\item {} \emph{hlast} -- step size taken on the last internal step. -\item {} +\item {} \emph{hcur} -- step size to be attempted on the next internal step. -\item {} +\item {} \emph{tcur} -- current internal time reached. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15622,7 +15672,7 @@ \subsubsection{Main solver optional output functions} Returns the name of the ERKStep constant corresponding to \emph{flag}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{flag} -- a return flag from an ERKStep function. \end{itemize} @@ -15643,19 +15693,19 @@ \subsubsection{Main solver optional output functions} taken by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{expsteps} -- number of stability-limited steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15672,19 +15722,19 @@ \subsubsection{Main solver optional output functions} taken by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{accsteps} -- number of accuracy-limited steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15700,19 +15750,19 @@ \subsubsection{Main solver optional output functions} Returns the cumulative number of steps attempted by the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{step\_attempts} -- number of steps attempted by solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15729,19 +15779,19 @@ \subsubsection{Main solver optional output functions} side function, \(f\) (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{nf\_evals} -- number of calls to the user's \(f(t,y)\) function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15758,19 +15808,19 @@ \subsubsection{Main solver optional output functions} have occurred (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{netfails} -- number of error test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15786,19 +15836,19 @@ \subsubsection{Main solver optional output functions} Returns the Butcher table currently in use by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{B} -- pointer to Butcher table structure. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15834,19 +15884,19 @@ \subsubsection{Main solver optional output functions} for the current step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{ele} -- vector of estimated local truncation errors. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15877,31 +15927,31 @@ \subsubsection{Main solver optional output functions} Returns many of the most useful time-stepper statistics in a single call. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{expsteps} -- number of stability-limited steps taken in the solver. -\item {} +\item {} \emph{accsteps} -- number of accuracy-limited steps taken in the solver. -\item {} +\item {} \emph{step\_attempts} -- number of steps attempted by the solver. -\item {} +\item {} \emph{nf\_evals} -- number of calls to the user's \(f(t,y)\) function. -\item {} +\item {} \emph{netfails} -- number of error test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15917,19 +15967,19 @@ \subsubsection{Main solver optional output functions} Returns the cumulative number of constraint test failures (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{nconstrfails} -- number of constraint test failures. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -15944,19 +15994,19 @@ \subsubsection{Rootfinding optional output functions} \label{ERKStep_c_interface/User_callable:rootfinding-optional-output-functions}\label{ERKStep_c_interface/User_callable:erkstep-cinterface-erksteprootoutputs} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Array showing roots found - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetRootInfo]{\emph{\code{ERKStepGetRootInfo()}}}} \\ \hline No. of calls to user root function - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepGetNumGEvals]{\emph{\code{ERKStepGetNumGEvals()}}}} \\ \hline\end{tabulary} @@ -15969,10 +16019,10 @@ \subsubsection{Rootfinding optional output functions} have a root. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{rootsfound} -- array of length \emph{nrtfn} with the indices of the user functions \(g_i\) found to have a root (the value of \emph{nrtfn} was supplied in the call to @@ -15983,10 +16033,10 @@ \subsubsection{Rootfinding optional output functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -16011,19 +16061,19 @@ \subsubsection{Rootfinding optional output functions} user's root function \(g\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{ngevals} -- number of calls made to \(g\) so far. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -16046,19 +16096,19 @@ \subsubsection{General usability functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional routine -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Output all ERKStep solver parameters - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepWriteParameters]{\emph{\code{ERKStepWriteParameters()}}}} \\ \hline Output the current Butcher table - & + & {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepWriteButcher]{\emph{\code{ERKStepWriteButcher()}}}} \\ \hline\end{tabulary} @@ -16070,19 +16120,19 @@ \subsubsection{General usability functions} Outputs all ERKStep solver parameters to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the solver parameters. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKS\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -16105,19 +16155,19 @@ \subsubsection{General usability functions} Outputs the current Butcher table to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} \end{itemize} @@ -16182,32 +16232,32 @@ \subsection{ERKStep re-initialization functions} ERKStep time-stepper module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{f} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the right-hand side function in \(\dot{y} = f(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if a memory allocation failed -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -16262,42 +16312,42 @@ \subsection{ERKStep system resize function} comparable dynamical time scale. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ERKStep memory block. -\item {} +\item {} \emph{ynew} -- the newly-sized solution vector, holding the current dependent variable values \(y(t_0)\). -\item {} +\item {} \emph{hscale} -- the desired scaling factor for the dynamical time scale (i.e. the next step will be of size \emph{h*hscale}). -\item {} +\item {} \emph{t0} -- the current value of the independent variable \(t_0\) (this must be consistent with \emph{ynew}). -\item {} +\item {} \emph{resize} -- the user-supplied vector resize function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKVecResizeFn]{\emph{\code{ARKVecResizeFn()}}}}. -\item {} +\item {} \emph{resize\_data} -- the user-supplied data structure to be passed to \emph{resize} when modifying internal ERKStep vectors. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ERKStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -16335,26 +16385,26 @@ \section{User-supplied functions} \label{ERKStep_c_interface/User_supplied:erkstep-cinterface-usersupplied}\label{ERKStep_c_interface/User_supplied:user-supplied-functions}\label{ERKStep_c_interface/User_supplied::doc} The user-supplied functions for ERKStep consist of: \begin{itemize} -\item {} +\item {} a function that defines the ODE (required), -\item {} +\item {} a function that handles error and warning messages (optional), -\item {} +\item {} a function that provides the error weight vector (optional), -\item {} +\item {} a function that handles adaptive time step error control (optional), -\item {} +\item {} a function that handles explicit time step stability (optional), -\item {} +\item {} a function that defines the root-finding problem(s) to solve (optional), -\item {} +\item {} a function that handles vector resizing operations, if the underlying vector structure supports resizing (as opposed to deletion/recreation), and if the user plans to call @@ -16375,16 +16425,16 @@ \subsection{ODE right-hand side} value of the independent variable \(t\) and state vector \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{ydot} -- the output vector that forms the ODE RHS \(f(t,y)\). -\item {} +\item {} \emph{user\_data} -- the \emph{user\_data} pointer that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetUserData]{\emph{\code{ERKStepSetUserData()}}}}. \end{itemize} @@ -16427,19 +16477,19 @@ \subsection{Error message handler function} ERKStep and its sub-modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{error\_code} -- the error code. -\item {} +\item {} \emph{module} -- the name of the ERKStep module reporting the error. -\item {} +\item {} \emph{function} -- the name of the function in which the error occurred. -\item {} +\item {} \emph{msg} -- the error message. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{eh\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetErrHandlerFn]{\emph{\code{ERKStepSetErrHandlerFn()}}}}. @@ -16462,7 +16512,7 @@ \subsection{Error message handler function} \subsection{Error weight function} \label{ERKStep_c_interface/User_supplied:erkstep-cinterface-errorweight}\label{ERKStep_c_interface/User_supplied:error-weight-function} As an alternative to providing the relative and absolute tolerances, -the user may provide a function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn}}}} to compute a +the user may provide a function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn}}}} to compute a vector \emph{ewt} containing the weights in the WRMS norm \(\|v\|_{WRMS} = \left(\frac{1}{n} \sum_{i=1}^n \left(ewt_i\; v_i\right)^2 \right)^{1/2}\). These weights will be used in place of those defined @@ -16475,14 +16525,14 @@ \subsection{Error weight function} \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the dependent variable vector at which the weight vector is to be computed. -\item {} +\item {} \emph{ewt} -- the output vector containing the error weights. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetUserData]{\emph{\code{ERKStepSetUserData()}}}}. @@ -16508,7 +16558,7 @@ \subsection{Time step adaptivity function} \label{ERKStep_c_interface/User_supplied:time-step-adaptivity-function}\label{ERKStep_c_interface/User_supplied:erkstep-cinterface-adaptivityfn} As an alternative to using one of the built-in time step adaptivity methods for controlling solution error, the user may provide a -function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn}}}} to compute a target step size +function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn}}}} to compute a target step size \(h\) for the next integration step. These steps should be chosen as the maximum value such that the error estimates remain below 1. \index{ARKAdaptFn (C type)} @@ -16519,40 +16569,40 @@ \subsection{Time step adaptivity function} that chooses \(h\) satisfying the error tolerances. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{h1} -- the current step size, \(t_n - t_{n-1}\). -\item {} +\item {} \emph{h2} -- the previous step size, \(t_{n-1} - t_{n-2}\). -\item {} +\item {} \emph{h3} -- the step size \(t_{n-2}-t_{n-3}\). -\item {} +\item {} \emph{e1} -- the error estimate from the current step, \(n\). -\item {} +\item {} \emph{e2} -- the error estimate from the previous step, \(n-1\). -\item {} +\item {} \emph{e3} -- the error estimate from the step \(n-2\). -\item {} +\item {} \emph{q} -- the global order of accuracy for the method. -\item {} +\item {} \emph{p} -- the global order of accuracy for the embedded method. -\item {} +\item {} \emph{hnew} -- the output value of the next step size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{h\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetAdaptivityFn]{\emph{\code{ERKStepSetAdaptivityFn()}}}}. @@ -16575,7 +16625,7 @@ \subsection{Explicit stability function} accuracy-based time step adaptivity algorithms may be sufficient for retaining a stable solution to the ODE system, these may be inefficient if \(f(t,y)\) contains moderately stiff terms. In -this scenario, a user may provide a function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn}}}} +this scenario, a user may provide a function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn}}}} to provide this stability information to ERKStep. This function must set the scalar step size satisfying the stability restriction for the upcoming time step. This value will subsequently be bounded by @@ -16588,17 +16638,17 @@ \subsection{Explicit stability function} This function predicts the maximum stable step size for the ODE system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{hstab} -- the output value with the absolute value of the maximum stable step size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{estab\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetStabilityFn]{\emph{\code{ERKStepSetStabilityFn()}}}}. @@ -16632,16 +16682,16 @@ \subsection{Rootfinding function} \(g_i(t,y)\) are sought. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{gout} -- the output array, of length \emph{nrtfn}, with components \(g_i(t,y)\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepSetUserData]{\emph{\code{ERKStepSetUserData()}}}}. @@ -16685,13 +16735,13 @@ \subsection{Vector resize function} supplied vector, \emph{ytemplate}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the vector to resize. -\item {} +\item {} \emph{ytemplate} -- a vector of the desired size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{resize\_data} parameter that was passed to {\hyperref[ERKStep_c_interface/User_callable:c.ERKStepResize]{\emph{\code{ERKStepResize()}}}}. @@ -16744,10 +16794,10 @@ \section{Access to library and header files} appropriate locations for the library and header files required by ARKode. The relevant library files are \begin{itemize} -\item {} +\item {} \code{libdir/libsundials\_arkode.lib}, -\item {} +\item {} \code{libdir/libsundials\_nvec*.lib}, \end{itemize} @@ -16756,13 +16806,13 @@ \section{Access to library and header files} libraries and \code{.a} for static libraries. The relevant header files are located in the subdirectories \begin{itemize} -\item {} +\item {} \code{incdir/include/arkode} -\item {} +\item {} \code{incdir/include/sundials} -\item {} +\item {} \code{incdir/include/nvector} \end{itemize} @@ -16861,7 +16911,7 @@ \section{Header Files} files so that various macros and data types can be used. The header file that is always required is: \begin{itemize} -\item {} +\item {} \code{arkode/arkode\_mristep.h}, the main header file for the MRIStep time-stepping module, which defines the several types and various constants, includes function prototypes, and includes the shared @@ -16893,14 +16943,14 @@ \section{A skeleton of the user's main program} referenced. \index{User main program}\begin{enumerate} -\item {} +\item {} Initialize parallel or multi-threaded environment, if appropriate. For example, call \code{MPI\_Init} to initialize MPI if used, or set \code{num\_threads}, the number of threads to use within the threaded vector functions, if used. -\item {} +\item {} Set problem dimensions, etc. This generally includes the problem size, \code{N}, and may include @@ -16911,7 +16961,7 @@ \section{A skeleton of the user's main program} \code{sunindextype}. \end{notice} -\item {} +\item {} Set vector of initial values To set the vector \code{y0} of initial values, use the appropriate @@ -16980,7 +17030,7 @@ \section{A skeleton of the user's main program} and device when instantiated. See the sections {\hyperref[nvectors/NVector_CUDA:nvectors-cuda]{\emph{\DUspan{}{The NVECTOR\_CUDA Module}}}} and {\hyperref[nvectors/NVector_RAJA:nvectors-raja]{\emph{\DUspan{}{The NVECTOR\_RAJA Module}}}} for details. -\item {} +\item {} Create an ARKStep object for the fast (inner) integration Call \code{inner\_arkode\_mem = ARKStepCreate(...)} to create the ARKStep memory @@ -16988,7 +17038,7 @@ \section{A skeleton of the user's main program} this memory structure. See the section {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-initialization]{\emph{\DUspan{}{ARKStep initialization and deallocation functions}}}} for details. -\item {} +\item {} Configure the fast integrator Specify tolerances, create and attach matrix and/or solver objects, @@ -17022,7 +17072,7 @@ \section{A skeleton of the user's main program} The \code{ARKStep} module used for the fast time scale must be configured with an identity mass matrix. -\item {} +\item {} Create an MRIStep object for the slow (outer) integration Call \code{arkode\_mem = MRIStepCreate(...)} to create the MRIStep memory @@ -17030,20 +17080,20 @@ \section{A skeleton of the user's main program} this memory structure. See the section {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-initialization]{\emph{\DUspan{}{MRIStep initialization and deallocation functions}}}} for details. -\item {} +\item {} Set the slow step size Call {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetFixedStep]{\emph{\code{MRIStepSetFixedStep()}}}} to specify the slow time step size. -\item {} +\item {} Set optional inputs Call \code{MRIStepSet*} functions to change any optional inputs that control the behavior of MRIStep from their default values. See the section {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for details. -\item {} +\item {} Specify rootfinding problem Optionally, call {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepRootInit]{\emph{\code{MRIStepRootInit()}}}} to initialize a rootfinding @@ -17052,7 +17102,7 @@ \section{A skeleton of the user's main program} the section {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}} for relevant optional input calls. -\item {} +\item {} Advance solution in time For each point at which output is desired, call @@ -17066,7 +17116,7 @@ \section{A skeleton of the user's main program} \(y(t_\text{out})\). See the section {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-integration]{\emph{\DUspan{}{MRIStep solver function}}}} for details. -\item {} +\item {} Get optional outputs Call \code{MRIStepGet*} and/or \code{ARKStepGet*} functions to obtain optional @@ -17074,7 +17124,7 @@ \section{A skeleton of the user's main program} the section {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}} and {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}} for details. -\item {} +\item {} Deallocate memory for solution vector Upon completion of the integration, deallocate memory for the @@ -17085,7 +17135,7 @@ \section{A skeleton of the user's main program} \PYG{n}{N\PYGZus{}VDestroy}\PYG{p}{(}\PYG{n}{y}\PYG{p}{)}\PYG{p}{;} \end{Verbatim} -\item {} +\item {} Free solver memory \begin{quote} @@ -17093,7 +17143,7 @@ \section{A skeleton of the user's main program} free the memory allocated for fast and slow integration modules respectively. \end{quote} -\item {} +\item {} Free linear solver and matrix memory \begin{quote} @@ -17102,7 +17152,7 @@ \section{A skeleton of the user's main program} linear solver and/or matrix objects created above for the fast integrator. \end{quote} -\item {} +\item {} Finalize MPI, if used \begin{quote} @@ -17140,22 +17190,22 @@ \subsection{MRIStep initialization and deallocation functions} be solved using the MRIStep time-stepping module in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{fs} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the slow portion of the right-hand side function in \(\dot{y} = f_s(t,y) + f_f(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). -\item {} +\item {} \emph{inner\_step\_id} -- the identifier for the inner stepper. Currently \code{MRISTEP\_ARKSTEP} is the only supported option. -\item {} +\item {} \emph{inner\_step\_mem} -- a \code{void*} pointer to the ARKStep memory block for integrating the fast time scale. @@ -17178,7 +17228,7 @@ \subsection{MRIStep initialization and deallocation functions} {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepCreate]{\emph{\code{MRIStepCreate()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. \end{itemize} @@ -17212,29 +17262,29 @@ \subsection{Rootfinding initialization function} {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepCreate]{\emph{\code{MRIStepCreate()}}}}, and before {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepEvolve]{\emph{\code{MRIStepEvolve()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{nrtfn} -- number of functions \(g_i\), an integer \(\ge\) 0. -\item {} +\item {} \emph{g} -- name of user-supplied function, of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRootFn]{\emph{\code{ARKRootFn()}}}}, defining the functions \(g_i\) whose roots are sought. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if there was a memory allocation failure -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if \emph{nrtfn} is greater than zero but \emph{g} = \code{NULL}. \end{itemize} @@ -17271,19 +17321,19 @@ \subsection{MRIStep solver function} Integrates the ODE over an interval in \(t\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{tout} -- the next time at which a computed solution is desired. -\item {} +\item {} \emph{yout} -- the computed solution vector. -\item {} +\item {} \emph{tret} -- the time corresponding to \emph{yout} (output). -\item {} +\item {} \emph{itask} -- a flag indicating the job of the solver for the next user step. @@ -17307,51 +17357,51 @@ \subsection{MRIStep solver function} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful. -\item {} +\item {} \emph{ARK\_ROOT\_RETURN} if {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepEvolve]{\emph{\code{MRIStepEvolve()}}}} succeeded, and found one or more roots. If the number of root functions, \emph{nrtfn}, is greater than 1, call {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetRootInfo]{\emph{\code{MRIStepGetRootInfo()}}}} to see which \(g_i\) were found to have a root at (\emph{*tret}). -\item {} +\item {} \emph{ARK\_TSTOP\_RETURN} if {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepEvolve]{\emph{\code{MRIStepEvolve()}}}} succeeded and returned at \emph{tstop}. -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the \emph{arkode\_mem} argument was \code{NULL}. -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if one of the inputs to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepEvolve]{\emph{\code{MRIStepEvolve()}}}} is illegal, or some other input to the solver was either illegal or missing. Details will be provided in the error message. Typical causes of this failure: \begin{enumerate} -\item {} +\item {} A component of the error weight vector became zero during internal time-stepping. -\item {} +\item {} A root of one of the root functions was found both at a point \(t\) and also very near \(t\). \end{enumerate} -\item {} +\item {} \emph{ARK\_TOO\_MUCH\_WORK} if the solver took \emph{mxstep} internal steps but could not reach \emph{tout}. The default value for \emph{mxstep} is \emph{MXSTEP\_DEFAULT = 500}. -\item {} +\item {} \emph{ARK\_VECTOROP\_ERR} a vector operation error occured. -\item {} +\item {} \emph{ARK\_INNERSTEP\_FAILED} if the inner stepper returned with an unrecoverable error. The value returned from the inner stepper can be obtained with {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetLastInnerStepFlag]{\emph{\code{MRIStepGetLastInnerStepFlag()}}}}. @@ -17403,10 +17453,10 @@ \subsection{Optional input functions} The optional inputs are grouped into the following categories: \begin{itemize} -\item {} +\item {} General MRIStep options ({\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-mristepinputtable]{\emph{\DUspan{}{Optional inputs for MRIStep}}}}), -\item {} +\item {} IVP method solver options ({\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-mristepmethodinputtable]{\emph{\DUspan{}{Optional inputs for IVP method selection}}}}), \end{itemize} @@ -17425,95 +17475,95 @@ \subsubsection{Optional inputs for MRIStep} \label{MRIStep_c_interface/User_callable:optional-inputs-for-mristep}\label{MRIStep_c_interface/User_callable:mristep-cinterface-mristepinputtable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Return MRIStep solver parameters to their defaults - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetDefaults]{\emph{\code{MRIStepSetDefaults()}}}} - & + & internal \\ \hline Set dense output order - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetDenseOrder]{\emph{\code{MRIStepSetDenseOrder()}}}} - & + & 3 \\ \hline Supply a pointer to a diagnostics output file - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetDiagnostics]{\emph{\code{MRIStepSetDiagnostics()}}}} - & + & \code{NULL} \\ \hline Supply a pointer to an error output file - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetErrFile]{\emph{\code{MRIStepSetErrFile()}}}} - & + & \code{stderr} \\ \hline Supply a custom error handler function - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetErrHandlerFn]{\emph{\code{MRIStepSetErrHandlerFn()}}}} - & + & internal fn \\ \hline Run with fixed-step sizes - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetFixedStep]{\emph{\code{MRIStepSetFixedStep()}}}} - & + & required \\ \hline Maximum no. of warnings for \(t_n+h = t_n\) - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetMaxHnilWarns]{\emph{\code{MRIStepSetMaxHnilWarns()}}}} - & + & 10 \\ \hline Maximum no. of internal steps before \emph{tout} - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetMaxNumSteps]{\emph{\code{MRIStepSetMaxNumSteps()}}}} - & + & 500 \\ \hline Set a value for \(t_{stop}\) - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetStopTime]{\emph{\code{MRIStepSetStopTime()}}}} - & + & \(\infty\) \\ \hline Supply a pointer for user data - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetUserData]{\emph{\code{MRIStepSetUserData()}}}} - & + & \code{NULL} \\ \hline Supply a function to be called prior to the inner integration - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPreInnerFn]{\emph{\code{MRIStepSetPreInnerFn()}}}} - & + & \code{NULL} \\ \hline Supply a function to be called after the inner integration - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetPostInnerFn]{\emph{\code{MRIStepSetPostInnerFn()}}}} - & + & \code{NULL} \\ \hline\end{tabulary} @@ -17527,19 +17577,19 @@ \subsubsection{Optional inputs for MRIStep} default values. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17562,22 +17612,22 @@ \subsubsection{Optional inputs for MRIStep} used for dense output (i.e. interpolation of solution output values). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{dord} -- requested polynomial order of accuracy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17597,22 +17647,22 @@ \subsubsection{Optional inputs for MRIStep} all MRIStep step adaptivity and solver information is written. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{diagfp} -- pointer to the diagnostics output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17639,22 +17689,22 @@ \subsubsection{Optional inputs for MRIStep} function is used. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{errfp} -- pointer to the output file. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17681,26 +17731,26 @@ \subsubsection{Optional inputs for MRIStep} in handling error messages. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{ehfun} -- name of user-supplied error handler function. -\item {} +\item {} \emph{eh\_data} -- pointer to user data passed to \emph{ehfun} every time it is called. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17719,22 +17769,22 @@ \subsubsection{Optional inputs for MRIStep} Set the slow and fast step size used within MRIStep. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{hs} -- value of the outer (slow) step size. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17770,22 +17820,22 @@ \subsubsection{Optional inputs for MRIStep} MRIStep will instead return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{mxhnil} -- maximum allowed number of warning messages \((>0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17808,22 +17858,22 @@ \subsubsection{Optional inputs for MRIStep} will return with an error. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{mxsteps} -- maximum allowed number of internal steps. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17845,22 +17895,22 @@ \subsubsection{Optional inputs for MRIStep} \(t\) past which the solution is not to proceed. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{tstop} -- stopping time for the integrator. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17879,22 +17929,22 @@ \subsubsection{Optional inputs for MRIStep} attaches it to the main MRIStep memory block. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{user\_data} -- pointer to the user data. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -17917,20 +17967,20 @@ \subsubsection{Optional inputs for MRIStep} Specifies the function called \emph{before} each inner integration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{prefn} -- the name of the C function (of type \code{ARKOuterToInner()}) defining pre inner integration function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} \end{itemize} @@ -17946,20 +17996,20 @@ \subsubsection{Optional inputs for MRIStep} Specifies the function called \emph{after} each inner integration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{postfn} -- the name of the C function (of type \code{ARKInnerToOuter()}) defining post inner integration function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} \end{itemize} @@ -17974,25 +18024,25 @@ \subsubsection{Optional inputs for IVP method selection} \label{MRIStep_c_interface/User_callable:optional-inputs-for-ivp-method-selection}\label{MRIStep_c_interface/User_callable:mristep-cinterface-mristepmethodinputtable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Set MRI outer RK table - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetTable]{\emph{\code{MRIStepSetTable()}}}} - & + & internal \\ \hline Specify MRI outer RK table number - & + & \code{MRIStepSetTableNum()} - & + & internal \\ \hline\end{tabulary} @@ -18004,25 +18054,25 @@ \subsubsection{Optional inputs for IVP method selection} Specifies a customized Butcher table for the MRI outer (slow) method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{q} -- global order of accuracy for the MRI method. -\item {} +\item {} \emph{B} -- the Butcher table for the outer (slow) RK method. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -18055,22 +18105,22 @@ \subsubsection{Optional inputs for IVP method selection} Indicates to use specific built-in Butcher table for the MRI outer (slow) method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{itable} -- index of the outer (slow) Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -18094,25 +18144,25 @@ \subsubsection{Rootfinding optional input functions} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional input -} & \textsf{\relax +} & \textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Default }\\ \hline Direction of zero-crossings to monitor - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetRootDirection]{\emph{\code{MRIStepSetRootDirection()}}}} - & + & both \\ \hline Disable inactive root warnings - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetNoInactiveRootWarn]{\emph{\code{MRIStepSetNoInactiveRootWarn()}}}} - & + & enabled \\ \hline\end{tabulary} @@ -18124,10 +18174,10 @@ \subsubsection{Rootfinding optional input functions} Specifies the direction of zero-crossings to be located and returned. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{rootdir} -- state array of length \emph{nrtfn}, the number of root functions \(g_i\) (the value of \emph{nrtfn} was supplied in the call to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepRootInit]{\emph{\code{MRIStepRootInit()}}}}). If \code{rootdir{[}i{]} == @@ -18139,13 +18189,13 @@ \subsubsection{Rootfinding optional input functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value \end{itemize} @@ -18164,16 +18214,16 @@ \subsubsection{Rootfinding optional input functions} to be identically zero at the beginning of the integration. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} \end{itemize} @@ -18221,35 +18271,35 @@ \subsection{Interpolated output function} range \{0,...,*dord*\}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{t} -- the value of the independent variable at which the derivative is to be evaluated. -\item {} +\item {} \emph{k} -- the derivative order requested. -\item {} +\item {} \emph{dky} -- output vector (must be allocated by the user). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_BAD\_K} if \emph{k} is not in the range \{0,...,*dord*\}. -\item {} +\item {} \emph{ARK\_BAD\_T} if \emph{t} is not in the interval \([t_n-h_n, t_n]\) -\item {} +\item {} \emph{ARK\_BAD\_DKY} if the \emph{dky} vector was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory is \code{NULL} \end{itemize} @@ -18272,19 +18322,19 @@ \subsection{Optional output functions} MRIStep provides an extensive set of functions that can be used to obtain solver performance information. We organize these into groups: \begin{enumerate} -\item {} +\item {} SUNDIALS version information accessor routines are in the subsection {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-sunversioninfo]{\emph{\DUspan{}{SUNDIALS version information}}}}, -\item {} +\item {} General MRIStep output routines are in the subsection {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-mristepmainoutputs]{\emph{\DUspan{}{Main solver optional output functions}}}}, -\item {} +\item {} Output routines regarding root-finding results are in the subsection {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-mristeprootoutputs]{\emph{\DUspan{}{Rootfinding optional output functions}}}}, -\item {} +\item {} General usability routines (e.g. to print the current MRIStep parameters, or output the current Butcher tables) are in the subsection {\hyperref[MRIStep_c_interface/User_callable:mristep-cinterface-mristepextraoutputs]{\emph{\DUspan{}{General usability functions}}}}. @@ -18297,7 +18347,7 @@ \subsection{Optional output functions} very useful in determining the efficiency of various methods inside MRIStep. For example: \begin{itemize} -\item {} +\item {} The counters \emph{nssteps}, \emph{nfsteps}, \emph{nfs\_evals}, and \emph{nff\_evals} provide a rough measure of the overall cost of a given run, and can be compared between runs with different solver options to suggest which set of options is the most @@ -18322,19 +18372,19 @@ \subsubsection{SUNDIALS version information} This routine fills a string with SUNDIALS version information. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{version} -- character array to hold the SUNDIALS version information. -\item {} +\item {} \emph{len} -- allocated length of the \emph{version} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS version \end{itemize} @@ -18355,28 +18405,28 @@ \subsubsection{SUNDIALS version information} release label if applicable. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{major} -- SUNDIALS release major version number. -\item {} +\item {} \emph{minor} -- SUNDIALS release minor version number. -\item {} +\item {} \emph{patch} -- SUNDIALS release patch version number. -\item {} +\item {} \emph{label} -- string to hold the SUNDIALS release label. -\item {} +\item {} \emph{len} -- allocated length of the \emph{label} character array. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} 0 if successful -\item {} +\item {} -1 if the input string is too short to store the SUNDIALS label \end{itemize} @@ -18395,44 +18445,44 @@ \subsubsection{Main solver optional output functions} \label{MRIStep_c_interface/User_callable:mristep-cinterface-mristepmainoutputs}\label{MRIStep_c_interface/User_callable:main-solver-optional-output-functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Size of MRIStep real and integer workspaces - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetWorkSpace]{\emph{\code{MRIStepGetWorkSpace()}}}} \\ \hline Cumulative numbers of internal steps - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetNumSteps]{\emph{\code{MRIStepGetNumSteps()}}}} \\ \hline Step size used for the last successful step - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetLastStep]{\emph{\code{MRIStepGetLastStep()}}}} \\ \hline Name of constant associated with a return flag - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetReturnFlagName]{\emph{\code{MRIStepGetReturnFlagName()}}}} \\ \hline No. of calls to the \emph{fs} and \emph{ff} functions - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetNumRhsEvals]{\emph{\code{MRIStepGetNumRhsEvals()}}}} \\ \hline Current MRI Butcher tables - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetCurrentButcherTables]{\emph{\code{MRIStepGetCurrentButcherTables()}}}} \\ \hline Last inner stepper return value - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetLastInnerStepFlag]{\emph{\code{MRIStepGetLastInnerStepFlag()}}}} \\ \hline\end{tabulary} @@ -18444,22 +18494,22 @@ \subsubsection{Main solver optional output functions} Returns the MRIStep real and integer workspace sizes. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{lenrw} -- the number of \code{realtype} values in the MRIStep workspace. -\item {} +\item {} \emph{leniw} -- the number of integer values in the MRIStep workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18476,22 +18526,22 @@ \subsubsection{Main solver optional output functions} the solver (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{nssteps} -- number of slow steps taken in the solver. -\item {} +\item {} \emph{nfsteps} -- number of fast steps taken in the solver. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18508,19 +18558,19 @@ \subsubsection{Main solver optional output functions} internal step. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{hlast} -- step size taken on the last internal step. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18536,19 +18586,19 @@ \subsubsection{Main solver optional output functions} Returns the current internal time reached by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{tcur} -- current internal time reached. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18564,7 +18614,7 @@ \subsubsection{Main solver optional output functions} Returns the name of the MRIStep constant corresponding to \emph{flag}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{flag} -- a return flag from an MRIStep function. \end{itemize} @@ -18585,19 +18635,19 @@ \subsubsection{Main solver optional output functions} \(fs\) (so far). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{nfs\_evals} -- number of calls to the user's \(fs(t,y)\) function. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18613,22 +18663,22 @@ \subsubsection{Main solver optional output functions} Returns the slow and fast Butcher tables currently in use by the solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{Bs} -- pointer to slow Butcher table structure. -\item {} +\item {} \emph{Bf} -- pointer to fast Butcher table structure. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18662,19 +18712,19 @@ \subsubsection{Main solver optional output functions} Returns the last return value from the inner stepper. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{flag} -- inner stepper return value. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18697,19 +18747,19 @@ \subsubsection{General usability functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional routine -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Output all MRIStep solver parameters - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepWriteParameters]{\emph{\code{MRIStepWriteParameters()}}}} \\ \hline Output the current Butcher tables - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepWriteButcher]{\emph{\code{MRIStepWriteButcher()}}}} \\ \hline\end{tabulary} @@ -18721,19 +18771,19 @@ \subsubsection{General usability functions} Outputs all MRIStep solver parameters to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the solver parameters. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARKS\_SUCCESS} if successful -\item {} +\item {} \emph{ARKS\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18756,19 +18806,19 @@ \subsubsection{General usability functions} Outputs the current Butcher tables to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{fp} -- pointer to use for printing the Butcher tables. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18790,19 +18840,19 @@ \subsubsection{Rootfinding optional output functions} \label{MRIStep_c_interface/User_callable:mristep-cinterface-mristeprootoutputs}\label{MRIStep_c_interface/User_callable:rootfinding-optional-output-functions} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax Function name }\\ \hline Array showing roots found - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetRootInfo]{\emph{\code{MRIStepGetRootInfo()}}}} \\ \hline No. of calls to user root function - & + & {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepGetNumGEvals]{\emph{\code{MRIStepGetNumGEvals()}}}} \\ \hline\end{tabulary} @@ -18815,10 +18865,10 @@ \subsubsection{Rootfinding optional output functions} have a root. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{rootsfound} -- array of length \emph{nrtfn} with the indices of the user functions \(g_i\) found to have a root (the value of \emph{nrtfn} was supplied in the call to @@ -18829,10 +18879,10 @@ \subsubsection{Rootfinding optional output functions} \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18857,19 +18907,19 @@ \subsubsection{Rootfinding optional output functions} user's root function \(g\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{ngevals} -- number of calls made to \(g\) so far. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} \end{itemize} @@ -18925,38 +18975,38 @@ \subsection{MRIStep re-initialization functions} MRIStep outer (slow) stepper. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{fs} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the slow right-hand side function in \(\dot{y} = f_s(t,y) + f_f(t,y)\). -\item {} +\item {} \emph{ff} -- the name of the C function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}}) defining the fast right-hand side function in \(\dot{y} = f_s(t,y) + f_f(t,y)\). -\item {} +\item {} \emph{t0} -- the initial value of \(t\). -\item {} +\item {} \emph{y0} -- the initial condition vector \(y(t_0)\). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_MEM\_FAIL} if a memory allocation failed -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -19001,38 +19051,38 @@ \subsection{MRIStep system resize function} Re-initializes MRIStep with a different state vector. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the MRIStep memory block. -\item {} +\item {} \emph{ynew} -- the newly-sized solution vector, holding the current dependent variable values \(y(t_0)\). -\item {} +\item {} \emph{t0} -- the current value of the independent variable \(t_0\) (this must be consistent with \emph{ynew}). -\item {} +\item {} \emph{resize} -- the user-supplied vector resize function (of type {\hyperref[MRIStep_c_interface/User_supplied:c.ARKVecResizeFn]{\emph{\code{ARKVecResizeFn()}}}}. -\item {} +\item {} \emph{resize\_data} -- the user-supplied data structure to be passed to \emph{resize} when modifying internal MRIStep vectors. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the MRIStep memory was \code{NULL} -\item {} +\item {} \emph{ARK\_NO\_MALLOC} if \emph{arkode\_mem} was not allocated. -\item {} +\item {} \emph{ARK\_ILL\_INPUT} if an argument has an illegal value. \end{itemize} @@ -19050,19 +19100,19 @@ \section{User-supplied functions} \label{MRIStep_c_interface/User_supplied:user-supplied-functions}\label{MRIStep_c_interface/User_supplied::doc}\label{MRIStep_c_interface/User_supplied:mristep-cinterface-usersupplied} The user-supplied functions for MRIStep consist of: \begin{itemize} -\item {} +\item {} functions that defines the ODE (required), -\item {} +\item {} a function that handles error and warning messages (optional), \end{itemize} \begin{itemize} -\item {} +\item {} a function that defines the root-finding problem(s) to solve (optional), -\item {} +\item {} a function that handles vector resizing operations, if the underlying vector structure supports resizing (as opposed to deletion/recreation), and if the user plans to call @@ -19083,16 +19133,16 @@ \subsection{ODE right-hand side} value of the independent variable \(t\) and state vector \(y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{ydot} -- the output vector that forms a portion the ODE RHS \(f(t,y)\). -\item {} +\item {} \emph{user\_data} -- the \emph{user\_data} pointer that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetUserData]{\emph{\code{MRIStepSetUserData()}}}}. \end{itemize} @@ -19129,19 +19179,19 @@ \subsection{Error message handler function} MRIStep and its sub-modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{error\_code} -- the error code. -\item {} +\item {} \emph{module} -- the name of the MRIStep module reporting the error. -\item {} +\item {} \emph{function} -- the name of the function in which the error occurred. -\item {} +\item {} \emph{msg} -- the error message. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{eh\_data} parameter that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetErrHandlerFn]{\emph{\code{MRIStepSetErrHandlerFn()}}}}. @@ -19174,16 +19224,16 @@ \subsection{Rootfinding function} \(g_i(t,y)\) are sought. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{gout} -- the output array, of length \emph{nrtfn}, with components \(g_i(t,y)\). -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{user\_data} parameter that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetUserData]{\emph{\code{MRIStepSetUserData()}}}}. @@ -19227,13 +19277,13 @@ \subsection{Vector resize function} supplied vector, \emph{ytemplate}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- the vector to resize. -\item {} +\item {} \emph{ytemplate} -- a vector of the desired size. -\item {} +\item {} \emph{user\_data} -- a pointer to user data, the same as the \emph{resize\_data} parameter that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepResize]{\emph{\code{MRIStepResize()}}}}. @@ -19264,16 +19314,16 @@ \subsection{Pre inner integrator communication function} \begin{fulllineitems} \phantomsection\label{MRIStep_c_interface/User_supplied:c.MRIStepPreInnerFn}\pysiglinewithargsret{typedef int \bfcode{(*MRIStepPreInnerFn)}}{realtype\emph{ t}, N\_Vector*\emph{ f}, int\emph{ num\_vecs}, void*\emph{ user\_data}}{}~\begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{f} -- an \code{N\_Vector} array of outer forcing vectors. -\item {} +\item {} \emph{num\_vecs} -- the number of vectors in the \code{N\_Vector} array. -\item {} +\item {} \emph{user\_data} -- the \emph{user\_data} pointer that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetUserData]{\emph{\code{MRIStepSetUserData()}}}}. @@ -19306,13 +19356,13 @@ \subsection{Post inner integrator communication function} \begin{fulllineitems} \phantomsection\label{MRIStep_c_interface/User_supplied:c.MRIStepPostInnerFn}\pysiglinewithargsret{typedef int \bfcode{(*MRIStepPostInnerFn)}}{realtype\emph{ t}, N\_Vector\emph{ y}, void*\emph{ user\_data}}{}~\begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{t} -- the current value of the independent variable. -\item {} +\item {} \emph{y} -- the current value of the dependent variable vector. -\item {} +\item {} \emph{user\_data} -- the \emph{user\_data} pointer that was passed to {\hyperref[MRIStep_c_interface/User_callable:c.MRIStepSetUserData]{\emph{\code{MRIStepSetUserData()}}}}. @@ -19350,11 +19400,11 @@ \section{ARKode Fortran 2003 Interface Modules} API using the intrinsic \code{iso\_c\_binding} module which provides a standardized mechanism for interoperating with C. AKRode provides four Fortran 2003 modules: \begin{itemize} -\item {} +\item {} \code{farkode\_arkstep\_mod}, \code{farkode\_erkstep\_mod}, \code{farkode\_mristep\_mod} provide interfaces to the ARKStep, ERKStep, and MRIStep time-stepping modules respectively -\item {} +\item {} \code{farkode\_mod} which interfaces to the components of ARKode which are shared by the time-stepping modules @@ -19409,9 +19459,9 @@ \subsubsection{Table: SUNDIALS Fortran 2003 Interface Modules} \label{ARKode_f_interface/F2003Module:table-sundials-fortran-2003-interface-modules}\label{ARKode_f_interface/F2003Module:fortran2003-interfacestable} \begin{longtable}{|l|l|} \hline -\textsf{\relax +\textsf{\relax \textbf{Module} -} & \textsf{\relax +} & \textsf{\relax \textbf{Fortran 2003 Module Name} }\\ \hline\endfirsthead @@ -19419,9 +19469,9 @@ \subsubsection{Table: SUNDIALS Fortran 2003 Interface Modules} \multicolumn{2}{c}% {{\textsf{\tablename\ \thetable{} -- continued from previous page}}} \\ \hline -\textsf{\relax +\textsf{\relax \textbf{Module} -} & \textsf{\relax +} & \textsf{\relax \textbf{Fortran 2003 Module Name} }\\ \hline\endhead @@ -19433,162 +19483,162 @@ \subsubsection{Table: SUNDIALS Fortran 2003 Interface Modules} NVECTOR - & + & \code{fsundials\_nvector\_mod} \\ \hline NVECTOR\_SERIAL - & + & \code{fnvector\_serial\_mod} \\ \hline NVECTOR\_OPENMP - & + & \code{fnvector\_openmp\_mod} \\ \hline NVECTOR\_PTHREADS - & + & \code{fnvector\_pthreads\_mod} \\ \hline NVECTOR\_PARALLEL - & + & \code{fnvector\_parallel\_mod} \\ \hline NVECTOR\_PARHYP - & + & Not interfaced \\ \hline NVECTOR\_PETSC - & + & Not interfaced \\ \hline NVECTOR\_CUDA - & + & Not interfaced \\ \hline NVECTOR\_RAJA - & + & Not interfaced \\ \hline NVECTOR\_MANVECTOR - & + & \code{fnvector\_manyvector\_mod} \\ \hline NVECTOR\_MPIMANVECTOR - & + & \code{fnvector\_mpimanyvector\_mod} \\ \hline NVECTOR\_MPIPLUSX - & + & \code{fnvector\_mpiplusx\_mod} \\ \hline SUNMATRIX - & + & \code{fsundials\_matrix\_mod} \\ \hline SUNMATRIX\_BAND - & + & \code{fsunmatrix\_band\_mod} \\ \hline SUNMATRIX\_DENSE - & + & \code{fsunmatrix\_dense\_mod} \\ \hline SUNMATRIX\_SPARSE - & + & \code{fsunmatrix\_sparse\_mod} \\ \hline SUNLINSOL - & + & \code{fsundials\_linearsolver\_mod} \\ \hline SUNLINSOL\_BAND - & + & \code{fsunlinsol\_band\_mod} \\ \hline SUNLINSOL\_DENSE - & + & \code{fsunlinsol\_dense\_mod} \\ \hline SUNLINSOL\_LAPACKBAND - & + & Not interfaced \\ \hline SUNLINSOL\_LAPACKDENSE - & + & Not interfaced \\ \hline SUNLINSOL\_KLU - & + & \code{fsunlinsol\_klu\_mod} \\ \hline SUNLINSOL\_SLUMT - & + & Not interfaced \\ \hline SUNLINSOL\_SLUDIST - & + & Not interfaced \\ \hline SUNLINSOL\_SPGMR - & + & \code{fsunlinsol\_spgmr\_mod} \\ \hline SUNLINSOL\_SPFGMR - & + & \code{fsunlinsol\_spfgmr\_mod} \\ \hline SUNLINSOL\_SPBCGS - & + & \code{fsunlinsol\_spbcgs\_mod} \\ \hline SUNLINSOL\_SPTFQMR - & + & \code{fsunlinsol\_sptfqmr\_mod} \\ \hline SUNLINSOL\_PCG - & + & \code{fsunlinsol\_pcg\_mof} \\ \hline SUNNONLINSOL - & + & \code{fsundials\_nonlinearsolver\_mod} \\ \hline SUNNONLINSOL\_NEWTON - & + & \code{fsunnonlinsol\_newton\_mod} \\ \hline SUNNONLINSOL\_FIXEDPOINT - & + & \code{fsunnonlinsol\_fixedpoint\_mod} \\ \hline\end{longtable} @@ -19612,11 +19662,11 @@ \subsubsection{Table: C/Fortran-2003 Equivalent Types} \label{ARKode_f_interface/F2003Module:table-c-fortran-2003-equivalent-types}\label{ARKode_f_interface/F2003Module:fortran2003-datatypestable} \begin{longtable}{|l|l|l|} \hline -\textsf{\relax +\textsf{\relax \textbf{C Type} -} & \textsf{\relax +} & \textsf{\relax \textbf{Parameter Direction} -} & \textsf{\relax +} & \textsf{\relax \textbf{Fortran 2003 type} }\\ \hline\endfirsthead @@ -19624,11 +19674,11 @@ \subsubsection{Table: C/Fortran-2003 Equivalent Types} \multicolumn{3}{c}% {{\textsf{\tablename\ \thetable{} -- continued from previous page}}} \\ \hline -\textsf{\relax +\textsf{\relax \textbf{C Type} -} & \textsf{\relax +} & \textsf{\relax \textbf{Parameter Direction} -} & \textsf{\relax +} & \textsf{\relax \textbf{Fortran 2003 type} }\\ \hline\endhead @@ -19640,219 +19690,219 @@ \subsubsection{Table: C/Fortran-2003 Equivalent Types} \code{double} - & + & in, inout, out, return - & + & \code{real(c\_double)} \\ \hline \code{int} - & + & in, inout, out, return - & + & \code{integer(c\_int)} \\ \hline \code{long} - & + & in, inout, out, return - & + & \code{integer(c\_long)} \\ \hline \code{booleantype} - & + & in, inout, out, return - & + & \code{integer(c\_int)} \\ \hline \code{realtype} - & + & in, inout, out, return - & + & \code{real(c\_double)} \\ \hline \code{sunindextype} - & + & in, inout, out, return - & + & \code{integer(c\_long)} \\ \hline \code{double*} - & + & in, inout, out - & + & \code{real(c\_double), dimension(*)} \\ \hline \code{double*} - & + & return - & + & \code{real(c\_double), pointer, dimension(:)} \\ \hline \code{int*} - & + & in, inout, out - & + & \code{real(c\_int), dimension(*)} \\ \hline \code{int*} - & + & return - & + & \code{real(c\_int), pointer, dimension(:)} \\ \hline \code{long*} - & + & in, inout, out - & + & \code{real(c\_long), dimension(*)} \\ \hline \code{long*} - & + & return - & + & \code{real(c\_long), pointer, dimension(:)} \\ \hline \code{realtype*} - & + & in, inout, out - & + & \code{real(c\_double), dimension(*)} \\ \hline \code{realtype*} - & + & return - & + & \code{real(c\_double), pointer, dimension(:)} \\ \hline \code{sunindextype*} - & + & in, inout, out - & + & \code{real(c\_long), dimension(*)} \\ \hline \code{sunindextype*} - & + & return - & + & \code{real(c\_long), pointer, dimension(:)} \\ \hline \code{realtype{[}{]}} - & + & in, inout, out - & + & \code{real(c\_double), dimension(*)} \\ \hline \code{sunindextype{[}{]}} - & + & in, inout, out - & + & \code{integer(c\_long), dimension(*)} \\ \hline \code{N\_Vector} - & + & in, inout, out - & + & \code{type(N\_Vector)} \\ \hline \code{N\_Vector} - & + & return - & + & \code{type(N\_Vector), pointer} \\ \hline \code{SUNMatrix} - & + & in, inout, out - & + & \code{type(SUNMatrix)} \\ \hline \code{SUNMatrix} - & + & return - & + & \code{type(SUNMatrix), pointer} \\ \hline \code{SUNLinearSolver} - & + & in, inout, out - & + & \code{type(SUNLinearSolver)} \\ \hline \code{SUNLinearSolver} - & + & return - & + & \code{type(SUNLinearSolver), pointer} \\ \hline \code{SUNNonlinearSolver} - & + & in, inout, out - & + & \code{type(SUNNonlinearSolver)} \\ \hline \code{SUNNonlinearSolver} - & + & return - & + & \code{type(SUNNonlinearSolver), pointer} \\ \hline \code{FILE*} - & + & in, inout, out, return - & + & \code{type(c\_ptr)} \\ \hline \code{void*} - & + & in, inout, out, return - & + & \code{type(c\_ptr)} \\ \hline \code{T**} - & + & in, inout, out, return - & + & \code{type(c\_ptr)} \\ \hline \code{T***} - & + & in, inout, out, return - & + & \code{type(c\_ptr)} \\ \hline \code{T****} - & + & in, inout, out, return - & + & \code{type(c\_ptr)} \\ \hline\end{longtable} @@ -20178,27 +20228,27 @@ \subsection{Fortran Data Types} 32-bit signed and 64-bit signed. This choice dictates the size of a SUNDIALS \code{sunindextype} variable. \begin{itemize} -\item {} +\item {} \code{int} -- equivalent to an \code{INTEGER} or \code{INTEGER*4} in Fortran -\item {} +\item {} \code{long int} -- this will depend on the computer architecture: \begin{itemize} -\item {} +\item {} 32-bit architecture -- equivalent to an \code{INTEGER} or \code{INTEGER*4} in Fortran -\item {} +\item {} 64-bit architecture -- equivalent to an \code{INTEGER*8} in Fortran \end{itemize} -\item {} +\item {} \code{sunindextype} -- this will depend on the SUNDIALS configuration: \begin{itemize} -\item {} +\item {} 32-bit -- equivalent to an \code{INTEGER} or \code{INTEGER*4} in Fortran -\item {} +\item {} 64-bit -- equivalent to an \code{INTEGER*8} in Fortran \end{itemize} @@ -20212,13 +20262,13 @@ \subsection{Fortran Data Types} \code{realtype} variable. The corresponding Fortran types for these \code{realtype} sizes are: \begin{itemize} -\item {} +\item {} \code{single} -- equivalent to a \code{REAL} or \code{REAL*4} in Fortran -\item {} +\item {} \code{double} -- equivalent to a \code{DOUBLE PRECISION} or \code{REAL*8} in Fortran -\item {} +\item {} \code{extended} -- equivalent to a \code{REAL*16} in Fortran \end{itemize} @@ -20251,23 +20301,23 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the NVECTOR modules} \label{ARKode_f_interface/Routines:interface-to-the-nvector-modules}\begin{itemize} -\item {} +\item {} \code{FNVINITS()} (defined by NVECTOR\_SERIAL) interfaces to {\hyperref[nvectors/NVector_Serial:c.N_VNewEmpty_Serial]{\emph{\code{N\_VNewEmpty\_Serial()}}}}. -\item {} +\item {} \code{FNVINITP()} (defined by NVECTOR\_PARALLEL) interfaces to {\hyperref[nvectors/NVector_Parallel:c.N_VNewEmpty_Parallel]{\emph{\code{N\_VNewEmpty\_Parallel()}}}}. -\item {} +\item {} \code{FNVINITOMP()} (defined by NVECTOR\_OPENMP) interfaces to {\hyperref[nvectors/NVector_OpenMP:c.N_VNewEmpty_OpenMP]{\emph{\code{N\_VNewEmpty\_OpenMP()}}}}. -\item {} +\item {} \code{FNVINITPTS()} (defined by NVECTOR\_PTHREADS) interfaces to {\hyperref[nvectors/NVector_Pthreads:c.N_VNewEmpty_Pthreads]{\emph{\code{N\_VNewEmpty\_Pthreads()}}}}. -\item {} +\item {} \code{FNVINITPH()} (defined by NVECTOR\_PARHYP) interfaces to {\hyperref[nvectors/NVector_ParHyp:c.N_VNewEmpty_ParHyp]{\emph{\code{N\_VNewEmpty\_ParHyp()}}}}. @@ -20276,15 +20326,15 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the SUNMATRIX modules} \label{ARKode_f_interface/Routines:interface-to-the-sunmatrix-modules}\begin{itemize} -\item {} +\item {} \code{FSUNBANDMATINIT()} (defined by SUNMATRIX\_BAND) interfaces to {\hyperref[sunmatrix/SUNMatrix_Band:c.SUNBandMatrix]{\emph{\code{SUNBandMatrix()}}}}. -\item {} +\item {} \code{FSUNDENSEMATINIT()} (defined by SUNMATRIX\_DENSE) interfaces to {\hyperref[sunmatrix/SUNMatrix_Dense:c.SUNDenseMatrix]{\emph{\code{SUNDenseMatrix()}}}}. -\item {} +\item {} \code{FSUNSPARSEMATINIT()} (defined by SUNMATRIX\_SPARSE) interfaces to {\hyperref[sunmatrix/SUNMatrix_Sparse:c.SUNSparseMatrix]{\emph{\code{SUNSparseMatrix()}}}}. @@ -20293,51 +20343,51 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the SUNLINSOL modules} \label{ARKode_f_interface/Routines:interface-to-the-sunlinsol-modules}\begin{itemize} -\item {} +\item {} \code{FSUNBANDLINSOLINIT()} (defined by SUNLINSOL\_BAND) interfaces to {\hyperref[sunlinsol/SUNLinSol_Band:c.SUNLinSol_Band]{\emph{\code{SUNLinSol\_Band()}}}}. -\item {} +\item {} \code{FSUNDENSELINSOLINIT()} (defined by SUNLINSOL\_DENSE) interfaces to {\hyperref[sunlinsol/SUNLinSol_Dense:c.SUNLinSol_Dense]{\emph{\code{SUNLinSol\_Dense()}}}}. -\item {} +\item {} \code{FSUNKLUINIT()} (defined by SUNLINSOL\_KLU) interfaces to {\hyperref[sunlinsol/SUNLinSol_KLU:c.SUNLinSol_KLU]{\emph{\code{SUNLinSol\_KLU()}}}}. -\item {} +\item {} \code{FSUNKLUREINIT()} (defined by SUNLINSOL\_KLU) interfaces to \code{SUNLinSol\_KLUReinit()}. -\item {} +\item {} \code{FSUNLAPACKBANDINIT()} (defined by SUNLINSOL\_LAPACKBAND) interfaces to {\hyperref[sunlinsol/SUNLinSol_LapackBand:c.SUNLinSol_LapackBand]{\emph{\code{SUNLinSol\_LapackBand()}}}}. -\item {} +\item {} \code{FSUNLAPACKDENSEINIT()} (defined by SUNLINSOL\_LAPACKDENSE) interfaces to {\hyperref[sunlinsol/SUNLinSol_LapackDense:c.SUNLinSol_LapackDense]{\emph{\code{SUNLinSol\_LapackDense()}}}}. -\item {} +\item {} \code{FSUNPCGINIT()} (defined by SUNLINSOL\_PCG) interfaces to {\hyperref[sunlinsol/SUNLinSol_PCG:c.SUNLinSol_PCG]{\emph{\code{SUNLinSol\_PCG()}}}}. -\item {} +\item {} \code{FSUNSPBCGSINIT()} (defined by SUNLINSOL\_SPBCGS) interfaces to {\hyperref[sunlinsol/SUNLinSol_SPBCGS:c.SUNLinSol_SPBCGS]{\emph{\code{SUNLinSol\_SPBCGS()}}}}. -\item {} +\item {} \code{FSUNSPFGMRINIT()} (defined by SUNLINSOL\_SPFGMR) interfaces to {\hyperref[sunlinsol/SUNLinSol_SPFGMR:c.SUNLinSol_SPFGMR]{\emph{\code{SUNLinSol\_SPFGMR()}}}}. -\item {} +\item {} \code{FSUNSPGMRINIT()} (defined by SUNLINSOL\_SPGMR) interfaces to {\hyperref[sunlinsol/SUNLinSol_SPGMR:c.SUNLinSol_SPGMR]{\emph{\code{SUNLinSol\_SPGMR()}}}}. -\item {} +\item {} \code{FSUNSPTFQMRINIT()} (defined by SUNLINSOL\_SPTFQMR) interfaces to {\hyperref[sunlinsol/SUNLinSol_SPTFQMR:c.SUNLinSol_SPTFQMR]{\emph{\code{SUNLinSol\_SPTFQMR()}}}}. -\item {} +\item {} \code{FSUNSUPERLUMTINIT()} (defined by SUNLINSOL\_SUPERLUMT) interfaces to {\hyperref[sunlinsol/SUNLinSol_SuperLUMT:c.SUNLinSol_SuperLUMT]{\emph{\code{SUNLinSol\_SuperLUMT()}}}}. @@ -20346,20 +20396,20 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the SUNNONLINSOL modules} \label{ARKode_f_interface/Routines:interface-to-the-sunnonlinsol-modules}\begin{itemize} -\item {} +\item {} \code{FSUNNEWTONINIT()} (defined by SUNNONLINSOL\_NEWTON) interfaces to {\hyperref[sunnonlinsol/SUNNonlinSol_Newton:c.SUNNonlinSol_Newton]{\emph{\code{SUNNonlinSol\_Newton()}}}}. -\item {} +\item {} \code{FSUNNEWTONSETMAXITERS()} (defined by SUNNONLINSOL\_NEWTON) interfaces to {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSetMaxIters]{\emph{\code{SUNNonlinSolSetMaxIters()}}}} for a SUNNONLINSOL\_NEWTON object. -\item {} +\item {} \code{FSUNFIXEDPOINTINIT()} (defined by SUNNONLINSOL\_FIXEDPOINT) interfaces to {\hyperref[sunnonlinsol/SUNNonlinSol_Newton:c.SUNNonlinSol_Newton]{\emph{\code{SUNNonlinSol\_Newton()}}}}. -\item {} +\item {} \code{FSUNFIXEDPOINTSETMAXITERS()} (defined by SUNNONLINSOL\_FIXEDPOINT) interfaces to {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSetMaxIters]{\emph{\code{SUNNonlinSolSetMaxIters()}}}} for a SUNNONLINSOL\_FIXEDPOINT object. @@ -20369,63 +20419,63 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the main ARKODE module} \label{ARKode_f_interface/Routines:interface-to-the-main-arkode-module}\begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepCreate]{\emph{\code{ARKStepCreate()}}}} and {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetUserData]{\emph{\code{ARKStepSetUserData()}}}}, as well as one of {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSStolerances]{\emph{\code{ARKStepSStolerances()}}}} or {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSVtolerances]{\emph{\code{ARKStepSVtolerances()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKREINIT]{\emph{\code{FARKREINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepReInit]{\emph{\code{ARKStepReInit()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKRESIZE]{\emph{\code{FARKRESIZE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResize]{\emph{\code{ARKStepResize()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETIIN]{\emph{\code{FARKSETIIN()}}}} and {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETRIN]{\emph{\code{FARKSETRIN()}}}} interface to the ARKStepSet* and ARKStepSet* functions (see {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionalinputs]{\emph{\DUspan{}{Optional input functions}}}}). -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWTSET]{\emph{\code{FARKEWTSET()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepWFtolerances]{\emph{\code{ARKStepWFtolerances()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKADAPTSET]{\emph{\code{FARKADAPTSET()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityFn]{\emph{\code{ARKStepSetAdaptivityFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKEXPSTABSET]{\emph{\code{FARKEXPSTABSET()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetStabilityFn]{\emph{\code{ARKStepSetStabilityFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETERKTABLE]{\emph{\code{FARKSETERKTABLE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETIRKTABLE]{\emph{\code{FARKSETIRKTABLE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETARKTABLES]{\emph{\code{FARKSETARKTABLES()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETRESTOLERANCE]{\emph{\code{FARKSETRESTOLERANCE()}}}} interfaces to either {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResStolerance]{\emph{\code{ARKStepResStolerance()}}}} and {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResVtolerance]{\emph{\code{ARKStepResVtolerance()}}}} \end{itemize} \begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKODE]{\emph{\code{FARKODE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}}, the ARKStepGet* functions (see {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}}), and to the optional output functions for the selected linear solver module (see {\hyperref[ARKStep_c_interface/User_callable:arkstep-cinterface-optionaloutputs]{\emph{\DUspan{}{Optional output functions}}}}). -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKDKY]{\emph{\code{FARKDKY()}}}} interfaces to the interpolated output function {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetDky]{\emph{\code{ARKStepGetDky()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Optional_output:f/_/FARKGETERRWEIGHTS]{\emph{\code{FARKGETERRWEIGHTS()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetErrWeights]{\emph{\code{ARKStepGetErrWeights()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Optional_output:f/_/FARKGETESTLOCALERR]{\emph{\code{FARKGETESTLOCALERR()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetEstLocalErrors]{\emph{\code{ARKStepGetEstLocalErrors()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKFREE]{\emph{\code{FARKFREE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepFree]{\emph{\code{ARKStepFree()}}}}. \end{itemize} @@ -20433,7 +20483,7 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the system nonlinear solver interface} \label{ARKode_f_interface/Routines:interface-to-the-system-nonlinear-solver-interface}\begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKNLSINIT]{\emph{\code{FARKNLSINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinearSolver]{\emph{\code{ARKStepSetNonlinearSolver()}}}}. \end{itemize} @@ -20441,25 +20491,25 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the system linear solver interfaces} \label{ARKode_f_interface/Routines:interface-to-the-system-linear-solver-interfaces}\begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetLinearSolver]{\emph{\code{ARKStepSetLinearSolver()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKDENSESETJAC]{\emph{\code{FARKDENSESETJAC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacFn]{\emph{\code{ARKStepSetJacFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKBANDSETJAC]{\emph{\code{FARKBANDSETJAC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacFn]{\emph{\code{ARKStepSetJacFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPARSESETJAC]{\emph{\code{FARKSPARSESETJAC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacFn]{\emph{\code{ARKStepSetJacFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETEPSLIN]{\emph{\code{FARKLSSETEPSLIN()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetEpsLin]{\emph{\code{ARKStepSetEpsLin()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETJAC]{\emph{\code{FARKLSSETJAC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetJacTimes]{\emph{\code{ARKStepSetJacTimes()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETPREC]{\emph{\code{FARKLSSETPREC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPreconditioner]{\emph{\code{ARKStepSetPreconditioner()}}}}. \end{itemize} @@ -20467,25 +20517,25 @@ \subsubsection{FARKODE routines} \paragraph{Interface to the mass matrix linear solver interfaces} \label{ARKode_f_interface/Routines:interface-to-the-mass-matrix-linear-solver-interfaces}\begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSMASSINIT]{\emph{\code{FARKLSMASSINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassLinearSolver]{\emph{\code{ARKStepSetMassLinearSolver()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKDENSESETMASS]{\emph{\code{FARKDENSESETMASS()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassFn]{\emph{\code{ARKStepSetMassFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKBANDSETMASS]{\emph{\code{FARKBANDSETMASS()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassFn]{\emph{\code{ARKStepSetMassFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPARSESETMASS]{\emph{\code{FARKSPARSESETMASS()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassFn]{\emph{\code{ARKStepSetMassFn()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASSEPSLIN]{\emph{\code{FARKLSSETMASSEPSLIN()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassEpsLin]{\emph{\code{ARKStepSetMassEpsLin()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASS]{\emph{\code{FARKLSSETMASS()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassTimes]{\emph{\code{ARKStepSetMassTimes()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASSPREC]{\emph{\code{FARKLSSETMASSPREC()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMassPreconditioner]{\emph{\code{ARKStepSetMassPreconditioner()}}}}. \end{itemize} @@ -20505,21 +20555,21 @@ \subsubsection{FARKODE routines} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax FARKODE routine (FORTRAN, user-supplied) -} & \textsf{\relax +} & \textsf{\relax ARKStep interface function type }\\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKIFUN]{\emph{\code{FARKIFUN()}}}} - & + & {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKEFUN]{\emph{\code{FARKEFUN()}}}} - & + & {\hyperref[MRIStep_c_interface/User_supplied:c.ARKRhsFn]{\emph{\code{ARKRhsFn()}}}} \\ \hline\end{tabulary} @@ -20533,132 +20583,132 @@ \subsubsection{FARKODE routines} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax FARKODE routine (FORTRAN, user-supplied) -} & \textsf{\relax +} & \textsf{\relax ARKStep interface function type -} & \textsf{\relax +} & \textsf{\relax FARKODE ``activation'' routine }\\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKDJAC]{\emph{\code{FARKDJAC()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacFn]{\emph{\code{ARKLsJacFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKDENSESETJAC]{\emph{\code{FARKDENSESETJAC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKBJAC]{\emph{\code{FARKBJAC()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacFn]{\emph{\code{ARKLsJacFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKBANDSETJAC]{\emph{\code{FARKBANDSETJAC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPJAC]{\emph{\code{FARKSPJAC()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacFn]{\emph{\code{ARKLsJacFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPARSESETJAC]{\emph{\code{FARKSPARSESETJAC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKDMASS]{\emph{\code{FARKDMASS()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassFn]{\emph{\code{ARKLsMassFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKDENSESETMASS]{\emph{\code{FARKDENSESETMASS()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKBMASS]{\emph{\code{FARKBMASS()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassFn]{\emph{\code{ARKLsMassFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKBANDSETMASS]{\emph{\code{FARKBANDSETMASS()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPMASS]{\emph{\code{FARKSPMASS()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassFn]{\emph{\code{ARKLsMassFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKSPARSESETMASS]{\emph{\code{FARKSPARSESETMASS()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSET]{\emph{\code{FARKPSET()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsPrecSetupFn]{\emph{\code{ARKLsPrecSetupFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETPREC]{\emph{\code{FARKLSSETPREC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSOL]{\emph{\code{FARKPSOL()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsPrecSolveFn]{\emph{\code{ARKLsPrecSolveFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETPREC]{\emph{\code{FARKLSSETPREC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTSETUP]{\emph{\code{FARKJTSETUP()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacTimesSetupFn]{\emph{\code{ARKLsJacTimesSetupFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETJAC]{\emph{\code{FARKLSSETJAC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTIMES]{\emph{\code{FARKJTIMES()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacTimesVecFn]{\emph{\code{ARKLsJacTimesVecFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETJAC]{\emph{\code{FARKLSSETJAC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSET]{\emph{\code{FARKMASSPSET()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassPrecSetupFn]{\emph{\code{ARKLsMassPrecSetupFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASSPREC]{\emph{\code{FARKLSSETMASSPREC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSOL]{\emph{\code{FARKMASSPSOL()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassPrecSolveFn]{\emph{\code{ARKLsMassPrecSolveFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASSPREC]{\emph{\code{FARKLSSETMASSPREC()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTSETUP]{\emph{\code{FARKMTSETUP()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassTimesSetupFn]{\emph{\code{ARKLsMassTimesSetupFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASS]{\emph{\code{FARKLSSETMASS()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTIMES]{\emph{\code{FARKMTIMES()}}}} - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassTimesVecFn]{\emph{\code{ARKLsMassTimesVecFn()}}}} - & + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSSETMASS]{\emph{\code{FARKLSSETMASS()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWT]{\emph{\code{FARKEWT()}}}} - & -{\hyperref[ARKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}} - & + & +{\hyperref[ERKStep_c_interface/User_supplied:c.ARKEwtFn]{\emph{\code{ARKEwtFn()}}}} + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWTSET]{\emph{\code{FARKEWTSET()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKADAPT]{\emph{\code{FARKADAPT()}}}} - & -{\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn()}}}} - & + & +{\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn()}}}} + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKADAPTSET]{\emph{\code{FARKADAPTSET()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKEXPSTAB]{\emph{\code{FARKEXPSTAB()}}}} - & -{\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn()}}}} - & + & +{\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn()}}}} + & {\hyperref[ARKode_f_interface/Usage:f/_/FARKEXPSTABSET]{\emph{\code{FARKEXPSTABSET()}}}} \\ \hline\end{tabulary} @@ -20692,24 +20742,24 @@ \subsubsection{Usage of the FARKODE interface module} variables \emph{Y} \(=y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing state variables. -\item {} +\item {} \emph{YDOT} (\code{realtype}, output) -- array containing state derivatives. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \textgreater{}0 recoverable error, \textless{}0 unrecoverable error). @@ -20729,24 +20779,24 @@ \subsubsection{Usage of the FARKODE interface module} variables \emph{Y} \(=y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing state variables. -\item {} +\item {} \emph{YDOT} (\code{realtype}, output) -- array containing state derivatives. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \textgreater{}0 recoverable error, \textless{}0 unrecoverable error). @@ -20947,43 +20997,43 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSVtolerances]{\emph{\code{ARKStepSVtolerances()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T0} (\code{realtype}, input) -- initial value of \(t\). -\item {} +\item {} \emph{Y0} (\code{realtype}, input) -- array of initial conditions. -\item {} +\item {} \emph{IMEX} (\code{int}, input) -- flag denoting basic integration method: 0 = implicit, 1 = explicit, 2 = ImEx. -\item {} +\item {} \emph{IATOL} (\code{int}, input) -- type for absolute tolerance input \emph{ATOL}: 1 = scalar, 2 = array, 3 = user-supplied function; the user must subsequently call {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWTSET]{\emph{\code{FARKEWTSET()}}}} and supply a routine {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWT]{\emph{\code{FARKEWT()}}}} to compute the error weight vector. -\item {} +\item {} \emph{RTOL} (\code{realtype}, input) -- scalar relative tolerance. -\item {} +\item {} \emph{ATOL} (\code{realtype}, input) -- scalar or array absolute tolerance. -\item {} +\item {} \emph{IOUT} (\code{long int}, input/output) -- array of length 29 for integer optional outputs. -\item {} +\item {} \emph{ROUT} (\code{realtype}, input/output) -- array of length 6 for real optional outputs. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array of user integer data, which will be passed unmodified to all user-provided routines. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array with user real data, which will be passed unmodified to all user-provided routines. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21012,21 +21062,21 @@ \subsubsection{Usage of the FARKODE interface module} vector \emph{EWT} for the calculation of the WRMS norm of \emph{Y}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing state variables. -\item {} +\item {} \emph{EWT} (\code{realtype}, output) -- array containing the error weight vector. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing the integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing the real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21046,10 +21096,10 @@ \subsubsection{Usage of the FARKODE interface module} Informs FARKODE to use the user-supplied {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWT]{\emph{\code{FARKEWT()}}}} function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag, use ``1'' to denoting to use {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWT]{\emph{\code{FARKEWT()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21076,14 +21126,14 @@ \subsubsection{Usage of the FARKODE interface module} to the {\hyperref[ARKode_f_interface/Usage:f/_/FARKODE]{\emph{\code{FARKODE()}}}} solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{KEY} (quoted string, input) -- which optional input is set (see {\hyperref[ARKode_f_interface/Usage:finterface-iinoptiontable]{\emph{\DUspan{}{Table: Keys for setting FARKODE integer optional inputs}}}}). -\item {} +\item {} \emph{IVAL} (\code{long int}, input) -- the integer input value to be used. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21098,104 +21148,104 @@ \subsubsection{Usage of the FARKODE interface module} \label{ARKode_f_interface/Usage:table-keys-for-setting-farkode-integer-optional-inputs}\label{ARKode_f_interface/Usage:finterface-iinoptiontable} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Key -} & \textsf{\relax +} & \textsf{\relax ARKStep routine }\\ \hline \code{ORDER} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetOrder]{\emph{\code{ARKStepSetOrder()}}}} \\ \hline \code{DENSE\_ORDER} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDenseOrder]{\emph{\code{ARKStepSetDenseOrder()}}}} \\ \hline \code{LINEAR} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetLinear]{\emph{\code{ARKStepSetLinear()}}}} \\ \hline \code{NONLINEAR} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinear]{\emph{\code{ARKStepSetNonlinear()}}}} \\ \hline \code{EXPLICIT} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetExplicit]{\emph{\code{ARKStepSetExplicit()}}}} \\ \hline \code{IMPLICIT} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetImplicit]{\emph{\code{ARKStepSetImplicit()}}}} \\ \hline \code{IMEX} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetImEx]{\emph{\code{ARKStepSetImEx()}}}} \\ \hline \code{IRK\_TABLE\_NUM} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}} \\ \hline \code{ERK\_TABLE\_NUM} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}} \\ \hline \code{ARK\_TABLE\_NUM} \emph{(a)} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}} \\ \hline \code{MAX\_NSTEPS} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNumSteps]{\emph{\code{ARKStepSetMaxNumSteps()}}}} \\ \hline \code{HNIL\_WARNS} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxHnilWarns]{\emph{\code{ARKStepSetMaxHnilWarns()}}}} \\ \hline \code{PREDICT\_METHOD} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetPredictorMethod]{\emph{\code{ARKStepSetPredictorMethod()}}}} \\ \hline \code{MAX\_ERRFAIL} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxErrTestFails]{\emph{\code{ARKStepSetMaxErrTestFails()}}}} \\ \hline \code{MAX\_CONVFAIL} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxConvFails]{\emph{\code{ARKStepSetMaxConvFails()}}}} \\ \hline \code{MAX\_NITERS} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNonlinIters]{\emph{\code{ARKStepSetMaxNonlinIters()}}}} \\ \hline \code{ADAPT\_SMALL\_NEF} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetSmallNumEFails]{\emph{\code{ARKStepSetSmallNumEFails()}}}} \\ \hline \code{LSETUP\_MSBP} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxStepsBetweenLSet]{\emph{\code{ARKStepSetMaxStepsBetweenLSet()}}}} \\ \hline \code{MAX\_CONSTR\_FAIL} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxNumConstrFails]{\emph{\code{ARKStepSetMaxNumConstrFails()}}}} \\ \hline\end{tabulary} @@ -21214,14 +21264,14 @@ \subsubsection{Usage of the FARKODE interface module} to the {\hyperref[ARKode_f_interface/Usage:f/_/FARKODE]{\emph{\code{FARKODE()}}}} solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{KEY} (quoted string, input) -- which optional input is set (see {\hyperref[ARKode_f_interface/Usage:finterface-rinoptiontable]{\emph{\DUspan{}{Table: Keys for setting FARKODE real optional inputs}}}}). -\item {} +\item {} \emph{RVAL} (\code{realtype}, input) -- the real input value to be used. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21236,94 +21286,94 @@ \subsubsection{Usage of the FARKODE interface module} \label{ARKode_f_interface/Usage:finterface-rinoptiontable}\label{ARKode_f_interface/Usage:table-keys-for-setting-farkode-real-optional-inputs} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Key -} & \textsf{\relax +} & \textsf{\relax ARKStep routine }\\ \hline \code{INIT\_STEP} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetInitStep]{\emph{\code{ARKStepSetInitStep()}}}} \\ \hline \code{MAX\_STEP} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxStep]{\emph{\code{ARKStepSetMaxStep()}}}} \\ \hline \code{MIN\_STEP} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMinStep]{\emph{\code{ARKStepSetMinStep()}}}} \\ \hline \code{STOP\_TIME} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetStopTime]{\emph{\code{ARKStepSetStopTime()}}}} \\ \hline \code{NLCONV\_COEF} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinConvCoef]{\emph{\code{ARKStepSetNonlinConvCoef()}}}} \\ \hline \code{ADAPT\_CFL} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetCFLFraction]{\emph{\code{ARKStepSetCFLFraction()}}}} \\ \hline \code{ADAPT\_SAFETY} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetSafetyFactor]{\emph{\code{ARKStepSetSafetyFactor()}}}} \\ \hline \code{ADAPT\_BIAS} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetErrorBias]{\emph{\code{ARKStepSetErrorBias()}}}} \\ \hline \code{ADAPT\_GROWTH} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxGrowth]{\emph{\code{ARKStepSetMaxGrowth()}}}} \\ \hline \code{ADAPT\_ETAMX1} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxFirstGrowth]{\emph{\code{ARKStepSetMaxFirstGrowth()}}}} \\ \hline \code{ADAPT\_BOUNDS} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetFixedStepBounds]{\emph{\code{ARKStepSetFixedStepBounds()}}}} \\ \hline \code{ADAPT\_ETAMXF} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxEFailGrowth]{\emph{\code{ARKStepSetMaxEFailGrowth()}}}} \\ \hline \code{ADAPT\_ETACF} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetMaxCFailGrowth]{\emph{\code{ARKStepSetMaxCFailGrowth()}}}} \\ \hline \code{NONLIN\_CRDOWN} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinCRDown]{\emph{\code{ARKStepSetNonlinCRDown()}}}} \\ \hline \code{NONLIN\_RDIV} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetNonlinRDiv]{\emph{\code{ARKStepSetNonlinRDiv()}}}} \\ \hline \code{LSETUP\_DGMAX} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetDeltaGammaMax]{\emph{\code{ARKStepSetDeltaGammaMax()}}}} \\ \hline \code{FIXED\_STEP} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetFixedStep]{\emph{\code{ARKStepSetFixedStep()}}}} \\ \hline\end{tabulary} @@ -21336,14 +21386,14 @@ \subsubsection{Usage of the FARKODE interface module} to the {\hyperref[ARKode_f_interface/Usage:f/_/FARKODE]{\emph{\code{FARKODE()}}}} solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{KEY} (quoted string, input) -- which optional input is set (see {\hyperref[ARKode_f_interface/Usage:finterface-vinoptiontable]{\emph{\DUspan{}{Table: Keys for setting FARKODE vector optional inputs}}}}). -\item {} +\item {} \emph{VVAL} (\code{realtype*}, input) -- the input vector of real values to be used. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21358,14 +21408,14 @@ \subsubsection{Usage of the FARKODE interface module} \label{ARKode_f_interface/Usage:finterface-vinoptiontable}\label{ARKode_f_interface/Usage:table-keys-for-setting-farkode-vector-optional-inputs} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Key -} & \textsf{\relax +} & \textsf{\relax ARKStep routine }\\ \hline \code{CONSTR\_VEC} - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetConstraints]{\emph{\code{ARKStepSetConstraints()}}}} \\ \hline\end{tabulary} @@ -21381,7 +21431,7 @@ \subsubsection{Usage of the FARKODE interface module} inputs to their default values. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21405,30 +21455,30 @@ \subsubsection{Usage of the FARKODE interface module} Interface to the routine {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{S} (\code{int}, input) -- number of stages in the table. -\item {} +\item {} \emph{Q} (\code{int}, input) -- global order of accuracy of the method. -\item {} +\item {} \emph{P} (\code{int}, input) -- global order of accuracy of the embedding. -\item {} +\item {} \emph{C} (\code{realtype}, input) -- array of length \emph{S} containing the stage times. -\item {} +\item {} \emph{A} (\code{realtype}, input) -- array of length \emph{S*S} containing the ERK coefficients (stored in row-major, ``C'', order). -\item {} +\item {} \emph{B} (\code{realtype}, input) -- array of length \emph{S} containing the solution coefficients. -\item {} +\item {} \emph{BEMBED} (\code{realtype}, input) -- array of length \emph{S} containing the embedding coefficients. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21444,30 +21494,30 @@ \subsubsection{Usage of the FARKODE interface module} Interface to the routine {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{S} (\code{int}, input) -- number of stages in the table. -\item {} +\item {} \emph{Q} (\code{int}, input) -- global order of accuracy of the method. -\item {} +\item {} \emph{P} (\code{int}, input) -- global order of accuracy of the embedding. -\item {} +\item {} \emph{C} (\code{realtype}, input) -- array of length \emph{S} containing the stage times. -\item {} +\item {} \emph{A} (\code{realtype}, input) -- array of length \emph{S*S} containing the IRK coefficients (stored in row-major, ``C'', order). -\item {} +\item {} \emph{B} (\code{realtype}, input) -- array of length \emph{S} containing the solution coefficients. -\item {} +\item {} \emph{BEMBED} (\code{realtype}, input) -- array of length \emph{S} containing the embedding coefficients. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21483,48 +21533,48 @@ \subsubsection{Usage of the FARKODE interface module} Interface to the routine {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTables]{\emph{\code{ARKStepSetTables()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{S} (\code{int}, input) -- number of stages in the table. -\item {} +\item {} \emph{Q} (\code{int}, input) -- global order of accuracy of the method. -\item {} +\item {} \emph{P} (\code{int}, input) -- global order of accuracy of the embedding. -\item {} +\item {} \emph{CI} (\code{realtype}, input) -- array of length \emph{S} containing the implicit stage times. -\item {} +\item {} \emph{CE} (\code{realtype}, input) -- array of length \emph{S} containing the explicit stage times. -\item {} +\item {} \emph{AI} (\code{realtype}, input) -- array of length \emph{S*S} containing the IRK coefficients (stored in row-major, ``C'', order). -\item {} +\item {} \emph{AE} (\code{realtype}, input) -- array of length \emph{S*S} containing the ERK coefficients (stored in row-major, ``C'', order). -\item {} +\item {} \emph{BI} (\code{realtype}, input) -- array of length \emph{S} containing the implicit solution coefficients. -\item {} +\item {} \emph{BE} (\code{realtype}, input) -- array of length \emph{S} containing the explicit solution coefficients. -\item {} +\item {} \emph{B2I} (\code{realtype}, input) -- array of length \emph{S} containing the implicit embedding coefficients. -\item {} +\item {} \emph{B2E} (\code{realtype}, input) -- array of length \emph{S} containing the explicit embedding coefficients. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21540,14 +21590,14 @@ \subsubsection{Usage of the FARKODE interface module} Interface to the routines {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResStolerance]{\emph{\code{ARKStepResStolerance()}}}} and {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepResVtolerance]{\emph{\code{ARKStepResVtolerance()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IATOL} (\code{int}, input) -- type for absolute residual tolerance input \emph{ATOL}: 1 = scalar, 2 = array. -\item {} +\item {} \emph{ATOL} (\code{realtype}, input) -- scalar or array absolute residual tolerance. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21569,24 +21619,24 @@ \subsubsection{Usage of the FARKODE interface module} the C routine {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetAdaptivityMethod]{\emph{\code{ARKStepSetAdaptivityMethod()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IMETHOD} (\code{int}, input) -- choice of adaptivity method. -\item {} +\item {} \emph{IDEFAULT} (\code{int}, input) -- flag denoting whether to use default parameters (1) or that customized parameters will be supplied (1). -\item {} +\item {} \emph{IPQ} (\code{int}, input) -- flag denoting whether to use the embedding order of accuracy (0) or the method order of accuracy (1) within step adaptivity algorithm. -\item {} +\item {} \emph{PARAMS} (\code{realtype}, input) -- array of 3 parameters to be used within the adaptivity strategy. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21601,7 +21651,7 @@ \subsubsection{Usage of the FARKODE interface module} The former of these is designed for advanced users who wish to investigate custom step adaptivity approaches as opposed to using any of those built-in to ARKStep. In ARKStep's C/C++ interface, this would be -provided by a function of type {\hyperref[ARKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn()}}}}; in the Fortran +provided by a function of type {\hyperref[ERKStep_c_interface/User_supplied:c.ARKAdaptFn]{\emph{\code{ARKAdaptFn()}}}}; in the Fortran interface this is provided through the user-supplied function: \index{FARKADAPT() (fortran subroutine)|textbf} @@ -21612,48 +21662,48 @@ \subsubsection{Usage of the FARKODE interface module} (\emph{E1}, \emph{E2}, \emph{E3}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing state variables. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{H1} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{H2} (\code{realtype}, input) -- previous step size. -\item {} +\item {} \emph{H3} (\code{realtype}, input) -- previous-previous step size. -\item {} +\item {} \emph{E1} (\code{realtype}, input) -- estimated temporal error in current step. -\item {} +\item {} \emph{E2} (\code{realtype}, input) -- estimated temporal error in previous step. -\item {} +\item {} \emph{E3} (\code{realtype}, input) -- estimated temporal error in previous-previous step. -\item {} +\item {} \emph{Q} (\code{int}, input) -- global order of accuracy for RK method. -\item {} +\item {} \emph{P} (\code{int}, input) -- global order of accuracy for RK embedded method. -\item {} +\item {} \emph{HNEW} (\code{realtype}, output) -- array containing the error weight vector. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing the integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing the real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21671,12 +21721,12 @@ \subsubsection{Usage of the FARKODE interface module} Informs FARKODE to use the user-supplied {\hyperref[ARKode_f_interface/Usage:f/_/FARKADAPT]{\emph{\code{FARKADAPT()}}}} function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag, use ``1'' to denoting to use {\hyperref[ARKode_f_interface/Usage:f/_/FARKADAPT]{\emph{\code{FARKADAPT()}}}}, or use ``0'' to denote a return to the default adaptivity strategy. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). @@ -21694,7 +21744,7 @@ \subsubsection{Usage of the FARKODE interface module} integration method is to be employed, the user may specify a function to provide the maximum explicitly-stable step for their problem. Again, in the C/C++ interface this would be a function of type -{\hyperref[ARKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn()}}}}, while in ARKStep's Fortran interface this +{\hyperref[ERKStep_c_interface/User_supplied:c.ARKExpStabFn]{\emph{\code{ARKExpStabFn()}}}}, while in ARKStep's Fortran interface this must be given through the user-supplied function: \index{FARKEXPSTAB() (fortran subroutine)|textbf} @@ -21704,24 +21754,24 @@ \subsubsection{Usage of the FARKODE interface module} on the current solution, \emph{Y}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing state variables. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{HSTAB} (\code{realtype}, output) -- maximum explicitly-stable step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing the integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing the real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -21739,12 +21789,12 @@ \subsubsection{Usage of the FARKODE interface module} Informs FARKODE to use the user-supplied {\hyperref[ARKode_f_interface/Usage:f/_/FARKEXPSTAB]{\emph{\code{FARKEXPSTAB()}}}} function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag, use ``1'' to denoting to use {\hyperref[ARKode_f_interface/Usage:f/_/FARKEXPSTAB]{\emph{\code{FARKEXPSTAB()}}}}, or use ``0'' to denote a return to the default error-based stability strategy. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). @@ -21773,7 +21823,7 @@ \subsubsection{Usage of the FARKODE interface module} specify use of a non-default nonlinear solver module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, -1 if a memory allocation error occurred, -2 for an illegal input). @@ -21803,7 +21853,7 @@ \subsubsection{Usage of the FARKODE interface module} attach a linear solver object (and optionally a matrix object) to ARKStep. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, -1 if a memory allocation error occurred, -2 for an illegal input). @@ -21831,37 +21881,37 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_DENSE or SUNLINSOL\_LAPACKDENSE solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NEQ} (\code{long int}, input) -- size of the ODE system. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing values of the dependent state variables. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- array containing values of the dependent state derivatives. -\item {} +\item {} \emph{DJAC} (\code{realtype} of size (NEQ,NEQ), output) -- 2D array containing the Jacobian entries. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -21895,11 +21945,11 @@ \subsubsection{Usage of the FARKODE interface module} Jacobian approximation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- any nonzero value specifies to use {\hyperref[ARKode_f_interface/Usage:f/_/FARKDJAC]{\emph{\code{FARKDJAC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -21924,47 +21974,47 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_BAND or SUNLINSOL\_LAPACKBAND solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NEQ} (\code{long int}, input) -- size of the ODE system. -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth. -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth. -\item {} +\item {} \emph{MDIM} (\code{long int}, input) -- leading dimension of \emph{BJAC} array. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing dependent state variables. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- array containing dependent state derivatives. -\item {} +\item {} \emph{BJAC} (\code{realtype} of size \emph{(MDIM,NEQ)}, output) -- 2D array containing the Jacobian entries. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -22003,11 +22053,11 @@ \subsubsection{Usage of the FARKODE interface module} Jacobian approximation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- any nonzero value specifies to use {\hyperref[ARKode_f_interface/Usage:f/_/FARKBJAC]{\emph{\code{FARKBJAC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -22035,49 +22085,49 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_KLU or SUNLINSOL\_SUPERLUMT solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing values of the dependent state variables. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- array containing values of the dependent state derivatives. -\item {} +\item {} \emph{N} (\code{sunindextype}, input) -- number of matrix rows and columns in Jacobian. -\item {} +\item {} \emph{NNZ} (\code{sunindextype}, input) -- allocated length of nonzero storage in Jacobian. -\item {} +\item {} \emph{JDATA} (\code{realtype} of size NNZ, output) -- nonzero values in Jacobian. -\item {} +\item {} \emph{JINDEXVALS} (\code{sunindextype} of size NNZ, output) -- row \emph{{[}CSR: column{]}} indices for each nonzero Jacobian entry. -\item {} +\item {} \emph{JINDEXPTRS} (\code{sunindextype} of size N+1, output) -- indices of where each column's \emph{{[}CSR: row's{]}} nonzeros begin in data array; last entry points just past end of data values. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -22116,7 +22166,7 @@ \subsubsection{Usage of the FARKODE interface module} been provided for the Jacobian approximation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -22145,12 +22195,12 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{EPLIFAC} (\code{realtype}, input) -- value to use for \(\epsilon_L\). Passing a value of 0 indicates to use the default value (0.05). -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22179,13 +22229,13 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag denoting use of user-supplied Jacobian-times-vector routines. A nonzero value specifies to use these the user-supplied routines, a zero value specifies not to use these. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22214,13 +22264,13 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag denoting use of user-supplied preconditioning routines. A nonzero value specifies to use these the user-supplied routines, a zero value specifies not to use these. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22251,37 +22301,37 @@ \subsubsection{Usage of the FARKODE interface module} Krylov iterative linear solvers. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{V} (\code{realtype}, input) -- array containing the vector to multiply. -\item {} +\item {} \emph{FJV} (\code{realtype}, output) -- array containing resulting product vector. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing dependent state variables. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- array containing dependent state derivatives. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WORK} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). \end{itemize} @@ -22309,27 +22359,27 @@ \subsubsection{Usage of the FARKODE interface module} \code{ARKLJacTimesSetupFn()}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- array containing dependent state variables. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- array containing dependent state derivatives. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). \end{itemize} @@ -22354,40 +22404,40 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsPrecSolveFn]{\emph{\code{ARKLsPrecSolveFn()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- current dependent state variable array. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- current dependent state variable derivative array. -\item {} +\item {} \emph{R} (\code{realtype}, input) -- right-hand side array. -\item {} +\item {} \emph{Z} (\code{realtype}, output) -- solution array. -\item {} +\item {} \emph{GAMMA} (\code{realtype}, input) -- Jacobian scaling factor. -\item {} +\item {} \emph{DELTA} (\code{realtype}, input) -- desired residual tolerance. -\item {} +\item {} \emph{LR} (\code{int}, input) -- flag denoting to solve the right or left preconditioner system: 1 = left preconditioner, 2 = right preconditioner. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable failure, \textless{}0 if a non-recoverable failure). @@ -22418,38 +22468,38 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsPrecSetupFn]{\emph{\code{ARKLsPrecSetupFn()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- current dependent state variable array. -\item {} +\item {} \emph{FY} (\code{realtype}, input) -- current dependent state variable derivative array. -\item {} +\item {} \emph{JOK} (\code{int}, input) -- flag indicating whether Jacobian-related data needs to be recomputed: 0 = recompute, 1 = reuse with the current value of \emph{GAMMA}. -\item {} +\item {} \emph{JCUR} (\code{realtype}, output) -- return flag to denote if Jacobian data was recomputed (1=yes, 0=no). -\item {} +\item {} \emph{GAMMA} (\code{realtype}, input) -- Jacobian scaling factor. -\item {} +\item {} \emph{H} (\code{realtype}, input) -- current step size. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable failure, \textless{}0 if a non-recoverable failure). @@ -22470,7 +22520,7 @@ \subsubsection{Usage of the FARKODE interface module} Notes: \begin{enumerate} -\item {} +\item {} If the user's {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTSETUP]{\emph{\code{FARKJTSETUP()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTIMES]{\emph{\code{FARKJTIMES()}}}} or {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSET]{\emph{\code{FARKPSET()}}}} routines use difference quotient approximations, they may need to use the error weight array \emph{EWT} @@ -22482,14 +22532,14 @@ \subsubsection{Usage of the FARKODE interface module} \begin{gather} \begin{split}\left(\sum_i \left(\rho_i\, EWT_i\right)^2 \right)^{1/2} < \delta.\end{split}\notag \end{gather} -\item {} +\item {} If needed in {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTSETUP]{\emph{\code{FARKJTSETUP()}}}} {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTIMES]{\emph{\code{FARKJTIMES()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSOL]{\emph{\code{FARKPSOL()}}}}, or {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSET]{\emph{\code{FARKPSET()}}}}, the error weight array \emph{EWT} can be obtained by calling {\hyperref[ARKode_f_interface/Optional_output:f/_/FARKGETERRWEIGHTS]{\emph{\code{FARKGETERRWEIGHTS()}}}} using a user-allocated array as temporary storage for \emph{EWT}. -\item {} +\item {} If needed in {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTSETUP]{\emph{\code{FARKJTSETUP()}}}} {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTIMES]{\emph{\code{FARKJTIMES()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSOL]{\emph{\code{FARKPSOL()}}}}, or {\hyperref[ARKode_f_interface/Usage:f/_/FARKPSET]{\emph{\code{FARKPSET()}}}}, the unit roundoff can be obtained as the optional output \emph{ROUT(6)} (available after @@ -22519,12 +22569,12 @@ \subsubsection{Usage of the FARKODE interface module} ARKStep's mass-matrix linear solver interface. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{TIME\_DEP} (\code{int}, input) -- flag indicating whether the mass matrix is time-dependent (1) or not (0). \emph{Currently, only values of ``0'' are supported} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, -1 if a memory allocation error occurred, -2 for an illegal input). @@ -22551,29 +22601,29 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_DENSE or SUNLINSOL\_LAPACKDENSE solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NEQ} (\code{long int}, input) -- size of the ODE system. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{DMASS} (\code{realtype} of size (NEQ,NEQ), output) -- 2D array containing the mass matrix entries. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -22599,7 +22649,7 @@ \subsubsection{Usage of the FARKODE interface module} for the mass matrix calculation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -22623,38 +22673,38 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_BAND or SUNLINSOL\_LAPACKBAND solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NEQ} (\code{long int}, input) -- size of the ODE system. -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth. -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth. -\item {} +\item {} \emph{MDIM} (\code{long int}, input) -- leading dimension of \emph{BMASS} array. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{BMASS} (\code{realtype} of size \emph{(MDIM,NEQ)}, output) -- 2D array containing the mass matrix entries. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -22684,7 +22734,7 @@ \subsubsection{Usage of the FARKODE interface module} matrix calculation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -22713,42 +22763,42 @@ \subsubsection{Usage of the FARKODE interface module} SUNLINSOL\_KLU or SUNLINSOL\_SUPERLUMT solver modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{N} (\code{sunindextype}, input) -- number of mass matrix rows and columns. -\item {} +\item {} \emph{NNZ} (\code{sunindextype}, input) -- allocated length of nonzero storage in mass matrix. -\item {} +\item {} \emph{MDATA} (\code{realtype} of size NNZ, output) -- nonzero values in mass matrix. -\item {} +\item {} \emph{MINDEXVALS} (\code{sunindextype} of size NNZ, output) -- row \emph{{[}CSR: column{]}} indices for each nonzero mass matrix entry. -\item {} +\item {} \emph{MINDEXPTRS} (\code{sunindextype} of size N+1, output) -- indices of where each column's \emph{{[}CSR: row's{]}} nonzeros begin in data array; last entry points just past end of data values. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{WK1}, \emph{WK2}, \emph{WK3} (\code{realtype}, input) -- array containing temporary workspace of same size as \emph{Y}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -22778,7 +22828,7 @@ \subsubsection{Usage of the FARKODE interface module} been provided for the mass matrix calculation. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error occurred). @@ -22808,12 +22858,12 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSMASSINIT]{\emph{\code{FARKLSMASSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{EPLIFAC} (\code{realtype}, input) -- value to use for \(\epsilon_L\). Passing a value of 0 indicates to use the default value (0.05). -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22844,24 +22894,24 @@ \subsubsection{Usage of the FARKODE interface module} Krylov iterative linear solvers. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{V} (\code{realtype}, input) -- array containing the vector to multiply. -\item {} +\item {} \emph{MV} (\code{realtype}, output) -- array containing resulting product vector. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). \end{itemize} @@ -22888,18 +22938,18 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassTimesSetupFn]{\emph{\code{ARKLsMassTimesSetupFn()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{IPAR} (\code{long int}, input) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). \end{itemize} @@ -22929,7 +22979,7 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSMASSINIT]{\emph{\code{FARKLSMASSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22958,11 +23008,11 @@ \subsubsection{Usage of the FARKODE interface module} This routine must be called \emph{after} {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSMASSINIT]{\emph{\code{FARKLSMASSINIT()}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{FLAG} (\code{int}, input) -- flag denoting use of user-supplied preconditioning routines. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -22984,19 +23034,19 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassPrecSetupFn]{\emph{\code{ARKLsMassPrecSetupFn()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable failure, \textless{}0 if a non-recoverable failure). @@ -23021,33 +23071,33 @@ \subsubsection{Usage of the FARKODE interface module} {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsMassPrecSolveFn]{\emph{\code{ARKLsMassPrecSolveFn()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{R} (\code{realtype}, input) -- right-hand side array. -\item {} +\item {} \emph{Z} (\code{realtype}, output) -- solution array. -\item {} +\item {} \emph{DELTA} (\code{realtype}, input) -- desired residual tolerance. -\item {} +\item {} \emph{LR} (\code{int}, input) -- flag denoting to solve the right or left preconditioner system: 1 = left preconditioner, 2 = right preconditioner. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable failure, \textless{}0 if a non-recoverable failure). @@ -23067,7 +23117,7 @@ \subsubsection{Usage of the FARKODE interface module} Notes: \begin{enumerate} -\item {} +\item {} If the user's {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSOL]{\emph{\code{FARKMASSPSOL()}}}} uses an iterative method in its solution, the residual vector \(\rho = r - Pz\) of the system should be made less than \(\delta =\) \emph{DELTA} in the @@ -23075,14 +23125,14 @@ \subsubsection{Usage of the FARKODE interface module} \begin{gather} \begin{split}\left(\sum_i \left(\rho_i\, EWT_i\right)^2 \right)^{1/2} < \delta.\end{split}\notag \end{gather} -\item {} +\item {} If needed in {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTIMES]{\emph{\code{FARKMTIMES()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTSETUP]{\emph{\code{FARKMTSETUP()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSOL]{\emph{\code{FARKMASSPSOL()}}}}, or {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSET]{\emph{\code{FARKMASSPSET()}}}}, the error weight array \emph{EWT} can be obtained by calling {\hyperref[ARKode_f_interface/Optional_output:f/_/FARKGETERRWEIGHTS]{\emph{\code{FARKGETERRWEIGHTS()}}}} using a user-allocated array as temporary storage for \emph{EWT}. -\item {} +\item {} If needed in {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTIMES]{\emph{\code{FARKMTIMES()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKMTSETUP]{\emph{\code{FARKMTSETUP()}}}}, {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSOL]{\emph{\code{FARKMASSPSOL()}}}}, or {\hyperref[ARKode_f_interface/Usage:f/_/FARKMASSPSET]{\emph{\code{FARKMASSPSET()}}}}, the unit roundoff can be obtained as the optional output \emph{ROUT(6)} @@ -23105,52 +23155,52 @@ \subsubsection{Usage of the FARKODE interface module} routines for reporting on solver statistics. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{TOUT} (\code{realtype}, input) -- next value of \(t\) at which a solution is desired. -\item {} +\item {} \emph{T} (\code{realtype}, output) -- value of independent variable that corresponds to the output \emph{Y} -\item {} +\item {} \emph{Y} (\code{realtype}, output) -- array containing dependent state variables on output. -\item {} +\item {} \emph{ITASK} (\code{int}, input) -- task indicator : \begin{itemize} -\item {} +\item {} 1 = normal mode (overshoot \emph{TOUT} and interpolate) -\item {} +\item {} 2 = one-step mode (return after each internal step taken) -\item {} +\item {} 3 = normal `tstop' mode (like 1, but integration never proceeds past \emph{TSTOP}, which must be specified through a preceding call to {\hyperref[ARKode_f_interface/Usage:f/_/FARKSETRIN]{\emph{\code{FARKSETRIN()}}}} using the key \emph{STOP\_TIME}) -\item {} +\item {} 4 = one step `tstop' mode (like 2, but integration never goes past \emph{TSTOP}). \end{itemize} -\item {} +\item {} \emph{IER} (int, output) -- completion flag: \begin{itemize} -\item {} +\item {} 0 = success, -\item {} +\item {} 1 = tstop return, -\item {} +\item {} 2 = root return, -\item {} +\item {} values -1, ..., -10 are failure modes (see {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepEvolve]{\emph{\code{ARKStepEvolve()}}}} and {\hyperref[Constants:constants]{\emph{\DUspan{}{Appendix: ARKode Constants}}}}). @@ -23187,18 +23237,18 @@ \subsubsection{Usage of the FARKODE interface module} point within the last step taken. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- time at which solution derivative is desired, within the interval \([t_n-h,t_n]\). -\item {} +\item {} \emph{K} (\code{int}, input) -- derivative order \((0 \le k \le 3)\). -\item {} +\item {} \emph{DKY} (\code{realtype}, output) -- array containing the computed \emph{K}-th derivative of \(y\). -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textless{}0 if an illegal argument). @@ -23264,48 +23314,48 @@ \subsubsection{Usage of the FARKODE interface module} differently-sized ODE system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T0} (\code{realtype}, input) -- initial value of the independent variable \(t\). -\item {} +\item {} \emph{Y0} (\code{realtype}, input) -- array of dependent-variable initial conditions. -\item {} +\item {} \emph{HSCALE} (\code{realtype}, input) -- desired step size scale factor: \begin{itemize} -\item {} +\item {} 1.0 is the default, -\item {} +\item {} any value \textless{}= 0.0 results in the default. \end{itemize} -\item {} +\item {} \emph{ITOL} (\code{int}, input) -- flag denoting that a new relative tolerance and vector of absolute tolerances are supplied in the \emph{RTOL} and \emph{ATOL} arguments: \begin{itemize} -\item {} +\item {} 0 = retain the current scalar-valued relative and absolute tolerances, or the user-supplied error weight function, {\hyperref[ARKode_f_interface/Usage:f/_/FARKEWT]{\emph{\code{FARKEWT()}}}}. -\item {} +\item {} 1 = \emph{RTOL} contains the new scalar-valued relative tolerance and \emph{ATOL} contains a new array of absolute tolerances. \end{itemize} -\item {} +\item {} \emph{RTOL} (\code{realtype}, input) -- scalar relative tolerance. -\item {} +\item {} \emph{ATOL} (\code{realtype}, input) -- array of absolute tolerances. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(\ne 0\) failure). \end{itemize} @@ -23387,102 +23437,102 @@ \subsubsection{FARKODE optional output} \label{ARKode_f_interface/Optional_output:table-optional-farkode-integer-outputs}\label{ARKode_f_interface/Optional_output:finterface-iouttable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax \emph{IOUT} Index -} & \textsf{\relax +} & \textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax ARKStep function }\\ \hline 1 - & + & LENRW - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetWorkSpace]{\emph{\code{ARKStepGetWorkSpace()}}}} \\ \hline 2 - & + & LENIW - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetWorkSpace]{\emph{\code{ARKStepGetWorkSpace()}}}} \\ \hline 3 - & + & NST - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumSteps]{\emph{\code{ARKStepGetNumSteps()}}}} \\ \hline 4 - & + & NST\_STB - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumExpSteps]{\emph{\code{ARKStepGetNumExpSteps()}}}} \\ \hline 5 - & + & NST\_ACC - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumAccSteps]{\emph{\code{ARKStepGetNumAccSteps()}}}} \\ \hline 6 - & + & NST\_ATT - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumStepAttempts]{\emph{\code{ARKStepGetNumStepAttempts()}}}} \\ \hline 7 - & + & NFE - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumRhsEvals]{\emph{\code{ARKStepGetNumRhsEvals()}}}} (num \(f^E\) calls) \\ \hline 8 - & + & NFI - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumRhsEvals]{\emph{\code{ARKStepGetNumRhsEvals()}}}} (num \(f^I\) calls) \\ \hline 9 - & + & NSETUPS - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumLinSolvSetups]{\emph{\code{ARKStepGetNumLinSolvSetups()}}}} \\ \hline 10 - & + & NETF - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumErrTestFails]{\emph{\code{ARKStepGetNumErrTestFails()}}}} \\ \hline 11 - & + & NNI - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumNonlinSolvIters]{\emph{\code{ARKStepGetNumNonlinSolvIters()}}}} \\ \hline 12 - & + & NCFN - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumNonlinSolvConvFails]{\emph{\code{ARKStepGetNumNonlinSolvConvFails()}}}} \\ \hline 13 - & + & NGE - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumGEvals]{\emph{\code{ARKStepGetNumGEvals()}}}} \\ \hline\end{tabulary} @@ -23493,53 +23543,53 @@ \subsubsection{FARKODE optional output} \label{ARKode_f_interface/Optional_output:table-optional-farkode-real-outputs}\label{ARKode_f_interface/Optional_output:finterface-routtable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax \emph{ROUT} Index -} & \textsf{\relax +} & \textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax ARKStep function }\\ \hline 1 - & + & H0U - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetActualInitStep]{\emph{\code{ARKStepGetActualInitStep()}}}} \\ \hline 2 - & + & HU - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetLastStep]{\emph{\code{ARKStepGetLastStep()}}}} \\ \hline 3 - & + & HCUR - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetCurrentStep]{\emph{\code{ARKStepGetCurrentStep()}}}} \\ \hline 4 - & + & TCUR - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetCurrentTime]{\emph{\code{ARKStepGetCurrentTime()}}}} \\ \hline 5 - & + & TOLSF - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetTolScaleFactor]{\emph{\code{ARKStepGetTolScaleFactor()}}}} \\ \hline 6 - & + & UROUND - & + & \code{UNIT\_ROUNDOFF} (see the section {\hyperref[ARKStep_c_interface/General:arkstep-cinterface-datatypes]{\emph{\DUspan{}{Data Types}}}}) \\ \hline\end{tabulary} @@ -23550,88 +23600,88 @@ \subsubsection{FARKODE optional output} \label{ARKode_f_interface/Optional_output:table-optional-arkls-interface-outputs}\label{ARKode_f_interface/Optional_output:finterface-lsiouttable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax \emph{IOUT} Index -} & \textsf{\relax +} & \textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax ARKStep function }\\ \hline 14 - & + & LENRWLS - & + & \code{ARKLsGetWorkSpace()} \\ \hline 15 - & + & LENIWLS - & + & \code{ARKLsGetWorkSpace()} \\ \hline 16 - & + & LSTF - & + & \code{ARKLsGetLastFlag()} \\ \hline 17 - & + & NFELS - & + & \code{ARKLsGetNumRhsEvals()} \\ \hline 18 - & + & NJE - & + & \code{ARKLsGetNumJacEvals()} \\ \hline 19 - & + & NJTS - & + & \code{ARKLsGetNumJTSetupEvals()} \\ \hline 20 - & + & NJTV - & + & \code{ARKLsGetNumJtimesEvals()} \\ \hline 21 - & + & NPE - & + & \code{ARKLsGetNumPrecEvals()} \\ \hline 22 - & + & NPS - & + & \code{ARKLsGetNumPrecSolves()} \\ \hline 23 - & + & NLI - & + & \code{ARKLsGetNumLinIters()} \\ \hline 24 - & + & NCFL - & + & \code{ARKLsGetNumConvFails()} \\ \hline\end{tabulary} @@ -23642,88 +23692,88 @@ \subsubsection{FARKODE optional output} \label{ARKode_f_interface/Optional_output:table-optional-arkls-mass-interface-outputs}\label{ARKode_f_interface/Optional_output:finterface-lsmassiouttable} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax \emph{IOUT} Index -} & \textsf{\relax +} & \textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax ARKStep function }\\ \hline 25 - & + & LENRWMS - & + & \code{ARKLsGetMassWorkSpace()} \\ \hline 26 - & + & LENIWMS - & + & \code{ARKLsGetMassWorkSpace()} \\ \hline 27 - & + & LSTMF - & + & \code{ARKLsGetLastMassFlag()} \\ \hline 28 - & + & NMSET - & + & \code{ARKLsGetNumMassSetups()} \\ \hline 29 - & + & NMSOL - & + & \code{ARKLsGetNumMassSolves()} \\ \hline 30 - & + & NMTSET - & + & \code{ARKLsGetNumMTSetups()} \\ \hline 31 - & + & NMMUL - & + & \code{ARKLsGetNumMassMult()} \\ \hline 32 - & + & NMPE - & + & \code{ARKLsGetNumMassPrecEvals()} \\ \hline 33 - & + & NMPS - & + & \code{ARKLsGetNumMassPrecSolves()} \\ \hline 34 - & + & NMLI - & + & \code{ARKLsGetNumMassIters()} \\ \hline 35 - & + & NMCFL - & + & \code{ARKLsGetNumMassConvFails()} \\ \hline\end{tabulary} @@ -23734,18 +23784,18 @@ \subsubsection{FARKODE optional output} \label{ARKode_f_interface/Optional_output:finterface-constriouttable}\label{ARKode_f_interface/Optional_output:table-optional-arkode-constraints-outputs} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax \emph{IOUT} Index -} & \textsf{\relax +} & \textsf{\relax Optional output -} & \textsf{\relax +} & \textsf{\relax ARKStep function }\\ \hline 36 - & + & CONSTRFAILS - & + & {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetNumConstrFails]{\emph{\code{ARKStepGetNumConstrFails()}}}} \\ \hline\end{tabulary} @@ -23769,11 +23819,11 @@ \subsubsection{FARKODE optional output} with {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetErrWeights]{\emph{\code{ARKStepGetErrWeights()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{EWT} (\code{realtype}, output) -- array containing the error weight vector. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -23799,11 +23849,11 @@ \subsubsection{FARKODE optional output} vector (interfaces with {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetEstLocalErrors]{\emph{\code{ARKStepGetEstLocalErrors()}}}}). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ELE} (\code{realtype}, output) -- array with the estimated local truncation error vector. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \(\ne 0\) if an error). @@ -23826,14 +23876,14 @@ \subsubsection{Usage of the FARKROOT interface to rootfinding} user-callable functions in FARKROOT, with the corresponding ARKStep functions, are as follows: \begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Rootfinding:f/_/FARKROOTINIT]{\emph{\code{FARKROOTINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepRootInit]{\emph{\code{ARKStepRootInit()}}}}, -\item {} +\item {} {\hyperref[ARKode_f_interface/Rootfinding:f/_/FARKROOTINFO]{\emph{\code{FARKROOTINFO()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepGetRootInfo]{\emph{\code{ARKStepGetRootInfo()}}}}, and -\item {} +\item {} {\hyperref[ARKode_f_interface/Rootfinding:f/_/FARKROOTFREE]{\emph{\code{FARKROOTFREE()}}}} interfaces to {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepRootInit]{\emph{\code{ARKStepRootInit()}}}}, freeing memory by calling the initializer with no root functions. @@ -23856,10 +23906,10 @@ \subsubsection{Usage of the FARKROOT interface to rootfinding} Initializes the Fortran interface to the FARKROOT module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NRTFN} (\code{int}, input) -- total number of root functions. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 if ARKStep memory is \code{NULL}, and -11 if a memory allocation error occurred). @@ -23883,24 +23933,24 @@ \subsubsection{Usage of the FARKROOT interface to rootfinding} \(g_i(t,y)=0\) are sought. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{T} (\code{realtype}, input) -- independent variable value \(t\). -\item {} +\item {} \emph{Y} (\code{realtype}, input) -- dependent variable array \(y\). -\item {} +\item {} \emph{G} (\code{realtype}, output) -- function value array \(g(t,y)\). -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- integer user data array, the same as the array passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- real-valued user data array, the same as the array passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(<0\) if error). @@ -23923,28 +23973,28 @@ \subsubsection{Usage of the FARKROOT interface to rootfinding} Initializes the Fortran interface to the FARKROOT module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NRTFN} (\code{int}, input) -- total number of root functions. -\item {} +\item {} \emph{INFO} (\code{int}, input/output) -- array of length \emph{NRTFN} with root information (must be allocated by the user). For each index, \emph{i = 1, ..., NRTFN}: \begin{itemize} -\item {} +\item {} \emph{INFO(i) = 1} if \(g_i(t,y)\) was found to have a root, and \(g_i\) is increasing. -\item {} +\item {} \emph{INFO(i) = -1} if \(g_i(t,y)\) was found to have a root, and \(g_i\) is decreasing. -\item {} +\item {} \emph{INFO(i) = 0} otherwise. \end{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, \(<0\) if error). @@ -23996,10 +24046,10 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} The two user-callable functions in this package, with the corresponding ARKStep function around which they wrap, are: \begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKBPINIT]{\emph{\code{FARKBPINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecInit]{\emph{\code{ARKBandPrecInit()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKBPOPT]{\emph{\code{FARKBPOPT()}}}} interfaces to the ARKBANDPRE optional output functions, {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetWorkSpace]{\emph{\code{ARKBandPrecGetWorkSpace()}}}} and {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetNumRhsEvals]{\emph{\code{ARKBandPrecGetNumRhsEvals()}}}}. @@ -24014,13 +24064,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} are unchanged from the main program described in the section {\hyperref[ARKode_f_interface/Usage:finterface-usage]{\emph{\DUspan{}{Usage of the FARKODE interface module}}}} are \emph{italicized}. \begin{enumerate} -\item {} +\item {} \emph{Right-hand side specification} -\item {} +\item {} \emph{NVECTOR module initialization} -\item {} +\item {} SUNLINSOL module initialization Initialize one of the iterative SUNLINSOL modules, by calling one @@ -24028,13 +24078,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} FSUNSPTFQMRINIT, supplying an argument to specify that the SUNLINSOL module should utilize left or right preconditioning. -\item {} +\item {} \emph{Problem specification} -\item {} +\item {} \emph{Set optional inputs} -\item {} +\item {} Linear solver interface specification First, initialize the ARKStep linear solver interface by calling {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}}. @@ -24055,19 +24105,19 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} with the ARKBANDPRE preconditioner. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NEQ} (\code{long int}, input) -- problem size. -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth of the band matrix that is retained as an approximation of the Jacobian. -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth of the band matrix approximation to the Jacobian. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, -1 if a memory failure). @@ -24078,10 +24128,10 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} \end{fulllineitems} -\item {} +\item {} \emph{Problem solution} -\item {} +\item {} ARKBANDPRE optional outputs Optional outputs for ARKStep's linear solver interface are listed in @@ -24095,17 +24145,17 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} Interfaces with the ARKBANDPRE optional output functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{LENRWBP} (\code{long int}, output) -- length of real preconditioner work space (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetWorkSpace]{\emph{\code{ARKBandPrecGetWorkSpace()}}}}). -\item {} +\item {} \emph{LENIWBP} (\code{long int}, output) -- length of integer preconditioner work space, in integer words (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetWorkSpace]{\emph{\code{ARKBandPrecGetWorkSpace()}}}}). -\item {} +\item {} \emph{NFEBP} (\code{long int}, output) -- number of \(f^I(t,y)\) evaluations (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBandPrecGetNumRhsEvals]{\emph{\code{ARKBandPrecGetNumRhsEvals()}}}}) @@ -24117,13 +24167,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} \end{fulllineitems} -\item {} +\item {} \emph{Additional solution output} -\item {} +\item {} \emph{Problem re-initialization} -\item {} +\item {} \emph{Memory deallocation} (The memory allocated for the FARKBP module is deallocated @@ -24144,13 +24194,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} The user-callable functions in this package, with the corresponding ARKStep and ARKBBDPRE functions, are as follows: \begin{itemize} -\item {} +\item {} {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKBBDINIT]{\emph{\code{FARKBBDINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecInit]{\emph{\code{ARKBBDPrecInit()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKBBDREINIT]{\emph{\code{FARKBBDREINIT()}}}} interfaces to {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecReInit]{\emph{\code{ARKBBDPrecReInit()}}}}. -\item {} +\item {} {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKBBDOPT]{\emph{\code{FARKBBDOPT()}}}} interfaces to the ARKBBDPRE optional output functions. @@ -24165,42 +24215,42 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax FARKBBD routine (FORTRAN, user-supplied) -} & \textsf{\relax +} & \textsf{\relax ARKStep routine (C, interface) -} & \textsf{\relax +} & \textsf{\relax ARKStep interface function type }\\ \hline {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKGLOCFN]{\emph{\code{FARKGLOCFN()}}}} - & + & FARKgloc - & + & {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKLocalFn]{\emph{\code{ARKLocalFn()}}}} \\ \hline {\hyperref[ARKode_f_interface/Preconditioning:f/_/FARKCOMMFN]{\emph{\code{FARKCOMMFN()}}}} - & + & FARKcfn - & + & {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKCommFn]{\emph{\code{ARKCommFn()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTIMES]{\emph{\code{FARKJTIMES()}}}} - & + & FARKJtimes - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacTimesVecFn]{\emph{\code{ARKLsJacTimesVecFn()}}}} \\ \hline {\hyperref[ARKode_f_interface/Usage:f/_/FARKJTSETUP]{\emph{\code{FARKJTSETUP()}}}} - & + & FARKJTSetup - & + & {\hyperref[ARKStep_c_interface/User_supplied:c.ARKLsJacTimesSetupFn]{\emph{\code{ARKLsJacTimesSetupFn()}}}} \\ \hline\end{tabulary} @@ -24217,13 +24267,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} unchanged from the main program described in the section {\hyperref[ARKode_f_interface/Usage:finterface-usage]{\emph{\DUspan{}{Usage of the FARKODE interface module}}}} are \emph{italicized}. \begin{enumerate} -\item {} +\item {} \emph{Right-hand side specification} -\item {} +\item {} \emph{NVECTOR module initialization} -\item {} +\item {} SUNLINSOL module initialization Initialize one of the iterative SUNLINSOL modules, by calling one @@ -24231,13 +24281,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} FSUNSPTFQMRINIT, supplying an argument to specify that the SUNLINSOL module should utilize left or right preconditioning. -\item {} +\item {} \emph{Problem specification} -\item {} +\item {} \emph{Set optional inputs} -\item {} +\item {} Linear solver interface specification First, initialize ARKStep's linear solver interface by @@ -24258,11 +24308,11 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} routine to initialize the ARKBBDPRE preconditioning module. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLOCAL} (\code{long int}, input) -- local vector size on this process. -\item {} +\item {} \emph{MUDQ} (\code{long int}, input) -- upper half-bandwidth to be used in the computation of the local Jacobian blocks by difference quotients. These may be smaller than the @@ -24270,27 +24320,27 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} of \(g\), when smaller values may provide greater efficiency. -\item {} +\item {} \emph{MLDQ} (\code{long int}, input) -- lower half-bandwidth to be used in the computation of the local Jacobian blocks by difference quotients. -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth of the band matrix that is retained as an approximation of the local Jacobian block (may be smaller than \emph{MUDQ}). -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth of the band matrix that is retained as an approximation of the local Jacobian block (may be smaller than \emph{MLDQ}). -\item {} +\item {} \emph{DQRELY} (\code{realtype}, input) -- relative increment factor in \(y\) for difference quotients (0.0 indicates to use the default). -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, -1 if a memory failure). @@ -24301,10 +24351,10 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} \end{fulllineitems} -\item {} +\item {} \emph{Problem solution} -\item {} +\item {} ARKBBDPRE optional outputs Optional outputs from the ARKStep linear solver interface are @@ -24318,17 +24368,17 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} Interfaces with the ARKBBDPRE optional output functions. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{LENRWBP} (\code{long int}, output) -- length of real preconditioner work space on this process (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecGetWorkSpace]{\emph{\code{ARKBBDPrecGetWorkSpace()}}}}). -\item {} +\item {} \emph{LENIWBP} (\code{long int}, output) -- length of integer preconditioner work space on this process (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecGetWorkSpace]{\emph{\code{ARKBBDPrecGetWorkSpace()}}}}). -\item {} +\item {} \emph{NGEBBD} (\code{long int}, output) -- number of \(g(t,y)\) evaluations (from {\hyperref[ARKStep_c_interface/Preconditioners:c.ARKBBDPrecGetNumGfnEvals]{\emph{\code{ARKBBDPrecGetNumGfnEvals()}}}}) so far. @@ -24340,10 +24390,10 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} \end{fulllineitems} -\item {} +\item {} \emph{Additional solution output} -\item {} +\item {} Problem re-initialization If a sequence of problems of the same size is being solved using @@ -24382,7 +24432,7 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} a call to {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}} must also be made; in this case the linear solver memory is reallocated. -\item {} +\item {} Problem resizing If a sequence of problems of different sizes (but with similar @@ -24417,13 +24467,13 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} a call to {\hyperref[ARKode_f_interface/Usage:f/_/FARKLSINIT]{\emph{\code{FARKLSINIT()}}}} must also be made; in this case the linear solver memory is reallocated. -\item {} +\item {} \emph{Memory deallocation} (The memory allocated for the FARKBBD module is deallocated automatically by {\hyperref[ARKode_f_interface/Usage:f/_/FARKFREE]{\emph{\code{FARKFREE()}}}}). -\item {} +\item {} User-supplied routines The following two routines must be supplied for use with the @@ -24437,31 +24487,31 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} the right-hand side function \(f^I(t,y)\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLOC} (\code{long int}, input) -- local problem size. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{YLOC} (\code{realtype}, input) -- array containing local dependent state variables. -\item {} +\item {} \emph{GLOC} (\code{realtype}, output) -- array containing local dependent state derivatives. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -24482,27 +24532,27 @@ \subsubsection{Usage of the FARKODE interface to built-in preconditioners} the input vector \emph{YLOC}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLOC} (\code{long int}, input) -- local problem size. -\item {} +\item {} \emph{T} (\code{realtype}, input) -- current value of the independent variable. -\item {} +\item {} \emph{YLOC} (\code{realtype}, input) -- array containing local dependent state variables. -\item {} +\item {} \emph{IPAR} (\code{long int}, input/output) -- array containing integer user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{RPAR} (\code{realtype}, input/output) -- array containing real user data that was passed to {\hyperref[ARKode_f_interface/Usage:f/_/FARKMALLOC]{\emph{\code{FARKMALLOC()}}}}. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 if success, \textgreater{}0 if a recoverable error occurred, \textless{}0 if an unrecoverable error occurred). @@ -24580,59 +24630,59 @@ \section{ARKodeButcherTable functions} \label{ARKodeButcherTable:arkodebutchertable-functions}\label{ARKodeButcherTable:id1} \begin{tabulary}{\linewidth}{|L|L|} \hline -\textsf{\relax +\textsf{\relax Function name -} & \textsf{\relax +} & \textsf{\relax Description }\\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_LoadERK]{\emph{\code{ARKodeButcherTable\_LoadERK()}}}} - & + & Retrieve a given explicit Butcher table by its unique name \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_LoadDIRK]{\emph{\code{ARKodeButcherTable\_LoadDIRK()}}}} - & + & Retrieve a given implicit Butcher table by its unique name \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Alloc]{\emph{\code{ARKodeButcherTable\_Alloc()}}}} - & + & Allocate an empty Butcher table \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Create]{\emph{\code{ARKodeButcherTable\_Create()}}}} - & + & Create a new Butcher table \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Copy]{\emph{\code{ARKodeButcherTable\_Copy()}}}} - & + & Create a copy of a Butcher table \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Space]{\emph{\code{ARKodeButcherTable\_Space()}}}} - & + & Get the Butcher table real and integer workspace size \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Free]{\emph{\code{ARKodeButcherTable\_Free()}}}} - & + & Deallocate a Butcher table \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_Write]{\emph{\code{ARKodeButcherTable\_Write()}}}} - & + & Write the Butcher table to an output file \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_CheckOrder]{\emph{\code{ARKodeButcherTable\_CheckOrder()}}}} - & + & Check the order of a Butcher table \\ \hline {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable_CheckARKOrder]{\emph{\code{ARKodeButcherTable\_CheckARKOrder()}}}} - & + & Check the order of an ARK pair of Butcher tables \\ \hline\end{tabulary} @@ -24647,16 +24697,16 @@ \section{ARKodeButcherTable functions} on these tables and their corresponding identifiers, see {\hyperref[Butcher:butcher]{\emph{\DUspan{}{Appendix: Butcher tables}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{emethod} -- integer input specifying the given Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable]{\emph{\code{ARKodeButcherTable}}}} structure if successful. -\item {} +\item {} \code{NULL} pointer if \emph{imethod} was invalid. \end{itemize} @@ -24676,16 +24726,16 @@ \section{ARKodeButcherTable functions} {\hyperref[Butcher:butcher]{\emph{\DUspan{}{Appendix: Butcher tables}}}}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{imethod} -- integer input specifying the given Butcher table. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable]{\emph{\code{ARKodeButcherTable}}}} structure if successful. -\item {} +\item {} \code{NULL} pointer if \emph{imethod} was invalid. \end{itemize} @@ -24701,20 +24751,20 @@ \section{ARKodeButcherTable functions} Allocates an empty Butcher table. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{stages} -- the number of stages in the Butcher table. -\item {} +\item {} \emph{embedded} -- flag denoting whether the Butcher table has an embedding (\code{SUNTRUE}) or not (\code{SUNFALSE}). \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable]{\emph{\code{ARKodeButcherTable}}}} structure if successful. -\item {} +\item {} \code{NULL} pointer if \emph{stages} was invalid or an allocation error occured. \end{itemize} @@ -24730,35 +24780,35 @@ \section{ARKodeButcherTable functions} Allocates a Butcher table and fills it with the given values. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{s} -- number of stages in the RK method. -\item {} +\item {} \emph{q} -- global order of accuracy for the RK method. -\item {} +\item {} \emph{p} -- global order of accuracy for the embedded RK method. -\item {} +\item {} \emph{c} -- array (of length \emph{s}) of stage times for the RK method. -\item {} +\item {} \emph{A} -- array of coefficients defining the RK stages. This should be stored as a 1D array of size \emph{s*s}, in row-major order. -\item {} +\item {} \emph{b} -- array of coefficients (of length \emph{s}) defining the time step solution. -\item {} +\item {} \emph{d} -- array of coefficients (of length \emph{s}) defining the embedded solution. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable]{\emph{\code{ARKodeButcherTable}}}} structure if successful. -\item {} +\item {} \code{NULL} pointer if \emph{stages} was invalid or an allocation error occured. \end{itemize} @@ -24777,16 +24827,16 @@ \section{ARKodeButcherTable functions} Creates copy of the given Butcher table. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B} -- the Butcher table to copy. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} {\hyperref[ARKodeButcherTable:c.ARKodeButcherTable]{\emph{\code{ARKodeButcherTable}}}} structure if successful. -\item {} +\item {} \code{NULL} pointer an allocation error occured. \end{itemize} @@ -24802,22 +24852,22 @@ \section{ARKodeButcherTable functions} Get the real and integer workspace size for a Butcher table. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B} -- the Butcher table. -\item {} +\item {} \emph{lenrw} -- the number of \code{realtype} values in the Butcher table workspace. -\item {} +\item {} \emph{leniw} -- the number of integer values in the Butcher table workspace. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful. -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the Butcher table memory was \code{NULL}. \end{itemize} @@ -24833,7 +24883,7 @@ \section{ARKodeButcherTable functions} Deallocate the Butcher table memory. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B} -- the Butcher table. \end{itemize} @@ -24849,10 +24899,10 @@ \section{ARKodeButcherTable functions} Write the Butcher table to the provided file pointer. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B} -- the Butcher table. -\item {} +\item {} \emph{outfile} -- pointer to use for printing the Butcher table. \end{itemize} @@ -24874,38 +24924,38 @@ \section{ARKodeButcherTable functions} used. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B} -- the Butcher table. -\item {} +\item {} \emph{q} -- the measured order of accuracy for the method. -\item {} +\item {} \emph{p} -- the measured order of accuracy for the embedding; 0 if the method does not have an embedding. -\item {} +\item {} \emph{outfile} -- file pointer for printing results; \code{NULL} to suppress output. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{0} -- success, the measured vales of \emph{q} and \emph{p} match the values of \emph{q} and \emph{p} in the provided Butcher tables. -\item {} +\item {} \emph{1} -- warning, the values of \emph{q} and \emph{p} in the provided Butcher tables are \emph{lower} than the measured values, or the measured values achieve the \emph{maximum order} possible with this function and the values of \emph{q} and \emph{p} in the provided Butcher tables table are higher. -\item {} +\item {} \emph{-1} -- failure, the values of \emph{q} and \emph{p} in the provided Butcher tables are \emph{higher} than the measured values. -\item {} +\item {} \emph{-2} -- failure, the input Butcher table or critical table contents are \code{NULL}. @@ -24927,37 +24977,37 @@ \section{ARKodeButcherTable functions} ARK pair of Butcher tables. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{B1} -- a Butcher table in the ARK pair. -\item {} +\item {} \emph{B2} -- a Butcher table in the ARK pair. -\item {} +\item {} \emph{q} -- the measured order of accuracy for the method. -\item {} +\item {} \emph{p} -- the measured order of accuracy for the embedding; 0 if the method does not have an embedding. -\item {} +\item {} \emph{outfile} -- file pointer for printing results; \code{NULL} to suppress output. \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{0} -- success, the measured vales of \emph{q} and \emph{p} match the values of \emph{q} and \emph{p} in the provided Butcher tables. -\item {} +\item {} \emph{1} -- warning, the values of \emph{q} and \emph{p} in the provided Butcher tables are \emph{lower} than the measured values, or the measured values achieve the \emph{maximum order} possible with this function and the values of \emph{q} and \emph{p} in the provided Butcher tables table are higher. -\item {} +\item {} \emph{-1} -- failure, the input Butcher tables or critical table contents are \code{NULL}. @@ -25166,109 +25216,109 @@ \subsection{Vector Identifications associated with vector kernels supplied with \label{nvectors/NVector_Description:nvector-vectorids}\label{nvectors/NVector_Description:vector-identifications-associated-with-vector-kernels-supplied-with-sundials} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Vector ID -} & \textsf{\relax +} & \textsf{\relax Vector type -} & \textsf{\relax +} & \textsf{\relax ID Value }\\ \hline SUNDIALS\_NVEC\_SERIAL - & + & Serial - & + & 0 \\ \hline SUNDIALS\_NVEC\_PARALLEL - & + & Distributed memory parallel (MPI) - & + & 1 \\ \hline SUNDIALS\_NVEC\_OPENMP - & + & OpenMP shared memory parallel - & + & 2 \\ \hline SUNDIALS\_NVEC\_PTHREADS - & + & PThreads shared memory parallel - & + & 3 \\ \hline SUNDIALS\_NVEC\_PARHYP - & + & \emph{hypre} ParHyp parallel vector - & + & 4 \\ \hline SUNDIALS\_NVEC\_PETSC - & + & PETSc parallel vector - & + & 5 \\ \hline SUNDIALS\_NVEC\_CUDA - & + & CUDA parallel vector - & + & 6 \\ \hline SUNDIALS\_NVEC\_RAJA - & + & RAJA parallel vector - & + & 7 \\ \hline SUNDIALS\_NVEC\_OPENMPDEV - & + & OpenMP parallel vector with device offloading - & + & 8 \\ \hline SUNDIALS\_NVEC\_TRILINOS - & + & Trilinos Tpetra vector - & + & 9 \\ \hline SUNDIALS\_NVEC\_MANYVECTOR - & + & ``ManyVector'' vector - & + & 10 \\ \hline SUNDIALS\_NVEC\_MPIMANYVECTOR - & + & MPI-enabled ``ManyVector'' vector - & + & 11 \\ \hline SUNDIALS\_NVEC\_MPIPLUSX - & + & MPI+X vector - & + & 12 \\ \hline SUNDIALS\_NVEC\_CUSTOM - & + & User-provided custom vector - & + & 13 \\ \hline\end{tabulary} @@ -25279,27 +25329,27 @@ \subsection{Implementing a custom NVECTOR} \label{nvectors/NVector_Description:nvector-custom-implementation}\label{nvectors/NVector_Description:implementing-a-custom-nvector} A particular implementation of the NVECTOR module must: \begin{itemize} -\item {} +\item {} Specify the \emph{content} field of \code{N\_Vector}. -\item {} +\item {} Define and implement the vector operations. Note that the names of these routines should be unique to that implementation in order to permit using more than one NVECTOR module (each with different \code{N\_Vector} internal data representations) in the same code. -\item {} +\item {} Define and implement user-callable constructor and destructor routines to create and free an \code{N\_Vector} with the new \emph{content} field and with \emph{ops} pointing to the new vector operations. -\item {} +\item {} Optionally, define and implement additional user-callable routines acting on the newly defined \code{N\_Vector} (e.g., a routine to print the content for debugging purposes). -\item {} +\item {} Optionally, provide accessor macros as needed for that particular implementation to be used to access different parts in the \emph{content} field of the newly defined \code{N\_Vector}. @@ -25336,7 +25386,7 @@ \subsection{Implementing a custom NVECTOR} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{v} -- an N\_Vector object \end{itemize} @@ -25355,10 +25405,10 @@ \subsection{Implementing a custom NVECTOR} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{w} -- the vector to copy operations from -\item {} +\item {} \emph{v} -- the vector to copy operations to \end{itemize} @@ -25391,34 +25441,34 @@ \subsubsection{Support for complex-valued vectors} vectors; however, some do not. To this end, we provide the following guidance: \begin{itemize} -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VMin]{\emph{\code{N\_VMin()}}}} and \code{N\_VMinLocal())()} should return the minimum of all \emph{real} components of the vector, i.e., \(m = \min_i \operatorname{real}(x_i)\). -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VConst]{\emph{\code{N\_VConst()}}}} (and similarly {\hyperref[nvectors/NVector_Operations:c.N_VConstVectorArray]{\emph{\code{N\_VConstVectorArray()}}}}) should set the real components of the vector to the input constant, and set all imaginary components to zero, i.e., \(z_i = c + 0 j,\: i=0,\ldots,n-1\). -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VAddConst]{\emph{\code{N\_VAddConst()}}}} should only update the real components of the vector with the input constant, leaving all imaginary components unchanged. -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VWrmsNorm]{\emph{\code{N\_VWrmsNorm()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VWrmsNormMask]{\emph{\code{N\_VWrmsNormMask()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumLocal]{\emph{\code{N\_VWSqrSumLocal()}}}} and {\hyperref[nvectors/NVector_Operations:c.N_VWSqrSumMaskLocal]{\emph{\code{N\_VWSqrSumMaskLocal()}}}} should assume that all entries of the weight vector \code{w} and the mask vector \code{id} are real-valued. -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VDotProd]{\emph{\code{N\_VDotProd()}}}} should mathematically return a complex number for complex-valued vectors; as this is not possible with SUNDIALS' current \code{realtype}, this routine should be set to \code{NULL} in the custom NVECTOR implementation. -\item {} +\item {} {\hyperref[nvectors/NVector_Operations:c.N_VCompare]{\emph{\code{N\_VCompare()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VConstrMask]{\emph{\code{N\_VConstrMask()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VMinQuotient]{\emph{\code{N\_VMinQuotient()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VConstrMaskLocal]{\emph{\code{N\_VConstrMaskLocal()}}}} and {\hyperref[nvectors/NVector_Operations:c.N_VMinQuotientLocal]{\emph{\code{N\_VMinQuotientLocal()}}}} are ill-defined due to the lack of a clear ordering in the @@ -26767,13 +26817,13 @@ \subsection{NVECTOR\_SERIAL functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of an \code{N\_Vector v}, it is more efficient to first obtain the component array via \code{v\_data = NV\_DATA\_S(v)} and then access \code{v\_data{[}i{]}} within the loop than it is to use \code{NV\_Ith\_S(v,i)} within the loop. -\item {} +\item {} {\hyperref[nvectors/NVector_Serial:c.N_VNewEmpty_Serial]{\emph{\code{N\_VNewEmpty\_Serial()}}}}, {\hyperref[nvectors/NVector_Serial:c.N_VMake_Serial]{\emph{\code{N\_VMake\_Serial()}}}}, and {\hyperref[nvectors/NVector_Serial:c.N_VCloneVectorArrayEmpty_Serial]{\emph{\code{N\_VCloneVectorArrayEmpty\_Serial()}}}} set the field \emph{own\_data} to \code{SUNFALSE}. The functions \code{N\_VDestroy\_Serial()} and @@ -26782,7 +26832,7 @@ \subsection{NVECTOR\_SERIAL functions} In such a case, it is the user's responsibility to deallocate the data pointer. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_SERIAL implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representation of these vectors. It is @@ -27208,13 +27258,13 @@ \subsection{NVECTOR\_PARALLEL functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of an \code{N\_Vector v}, it is more efficient to first obtain the local component array via \code{v\_data = NV\_DATA\_P(v)} and then access \code{v\_data{[}i{]}} within the loop than it is to use \code{NV\_Ith\_P(v,i)} within the loop. -\item {} +\item {} {\hyperref[nvectors/NVector_Parallel:c.N_VNewEmpty_Parallel]{\emph{\code{N\_VNewEmpty\_Parallel()}}}}, {\hyperref[nvectors/NVector_Parallel:c.N_VMake_Parallel]{\emph{\code{N\_VMake\_Parallel()}}}}, and {\hyperref[nvectors/NVector_Parallel:c.N_VCloneVectorArrayEmpty_Parallel]{\emph{\code{N\_VCloneVectorArrayEmpty\_Parallel()}}}} set the field \emph{own\_data} to \code{SUNFALSE}. The routines \code{N\_VDestroy\_Parallel()} and @@ -27223,7 +27273,7 @@ \subsection{NVECTOR\_PARALLEL functions} \code{SUNFALSE}. In such a case, it is the user's responsibility to deallocate the data pointer. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_PARALLEL implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representation of these vectors. It is @@ -27625,13 +27675,13 @@ \subsection{NVECTOR\_OPENMP functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of an \code{N\_Vector v}, it is more efficient to first obtain the component array via \code{v\_data = NV\_DATA\_OMP(v)} and then access \code{v\_data{[}i{]}} within the loop than it is to use \code{NV\_Ith\_OMP(v,i)} within the loop. -\item {} +\item {} {\hyperref[nvectors/NVector_OpenMP:c.N_VNewEmpty_OpenMP]{\emph{\code{N\_VNewEmpty\_OpenMP()}}}}, {\hyperref[nvectors/NVector_OpenMP:c.N_VMake_OpenMP]{\emph{\code{N\_VMake\_OpenMP()}}}}, and {\hyperref[nvectors/NVector_OpenMP:c.N_VCloneVectorArrayEmpty_OpenMP]{\emph{\code{N\_VCloneVectorArrayEmpty\_OpenMP()}}}} set the field \emph{own\_data} to \code{SUNFALSE}. The functions \code{N\_VDestroy\_OpenMP()} and @@ -27640,7 +27690,7 @@ \subsection{NVECTOR\_OPENMP functions} In such a case, it is the user's responsibility to deallocate the data pointer. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_OPENMP implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representation of these vectors. It is @@ -28051,13 +28101,13 @@ \subsection{NVECTOR\_PTHREADS functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of an \code{N\_Vector v}, it is more efficient to first obtain the component array via \code{v\_data = NV\_DATA\_PT(v)} and then access \code{v\_data{[}i{]}} within the loop than it is to use \code{NV\_Ith\_S(v,i)} within the loop. -\item {} +\item {} {\hyperref[nvectors/NVector_Pthreads:c.N_VNewEmpty_Pthreads]{\emph{\code{N\_VNewEmpty\_Pthreads()}}}}, {\hyperref[nvectors/NVector_Pthreads:c.N_VMake_Pthreads]{\emph{\code{N\_VMake\_Pthreads()}}}}, and {\hyperref[nvectors/NVector_Pthreads:c.N_VCloneVectorArrayEmpty_Pthreads]{\emph{\code{N\_VCloneVectorArrayEmpty\_Pthreads()}}}} set the field \emph{own\_data} to \code{SUNFALSE}. The functions \code{N\_VDestroy\_Pthreads()} and @@ -28066,7 +28116,7 @@ \subsection{NVECTOR\_PTHREADS functions} In such a case, it is the user's responsibility to deallocate the data pointer. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_PTHREADS implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representation of these vectors. It is @@ -28365,13 +28415,13 @@ \subsection{NVECTOR\_PARHYP functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When there is a need to access components of an \code{N\_Vector\_ParHyp v}, it is recommended to extract the HYPRE vector via \code{x\_vec = N\_VGetVector\_ParHyp(v)} and then access components using appropriate HYPRE functions. -\item {} +\item {} {\hyperref[nvectors/NVector_ParHyp:c.N_VNewEmpty_ParHyp]{\emph{\code{N\_VNewEmpty\_ParHyp()}}}}, {\hyperref[nvectors/NVector_ParHyp:c.N_VMake_ParHyp]{\emph{\code{N\_VMake\_ParHyp()}}}}, and {\hyperref[nvectors/NVector_ParHyp:c.N_VCloneVectorArrayEmpty_ParHyp]{\emph{\code{N\_VCloneVectorArrayEmpty\_ParHyp()}}}} set the field \emph{own\_parvector} to \code{SUNFALSE}. The functions \code{N\_VDestroy\_ParHyp()} and @@ -28380,7 +28430,7 @@ \subsection{NVECTOR\_PARHYP functions} set to \code{SUNFALSE}. In such a case, it is the user's responsibility to delete the underlying vector. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_PARHYP implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representations of these vectors. It is @@ -28639,7 +28689,7 @@ \subsection{NVECTOR\_PETSC functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When there is a need to access components of an \code{N\_Vector\_Petsc v}, it is recommeded to extract the PETSc vector via @@ -28647,7 +28697,7 @@ \subsection{NVECTOR\_PETSC functions} and then access components using appropriate PETSc functions. -\item {} +\item {} The functions {\hyperref[nvectors/NVector_PETSc:c.N_VNewEmpty_Petsc]{\emph{\code{N\_VNewEmpty\_Petsc()}}}}, {\hyperref[nvectors/NVector_PETSc:c.N_VMake_Petsc]{\emph{\code{N\_VMake\_Petsc()}}}}, and {\hyperref[nvectors/NVector_PETSc:c.N_VCloneVectorArrayEmpty_Petsc]{\emph{\code{N\_VCloneVectorArrayEmpty\_Petsc()}}}} set the field \emph{own\_data} to \code{SUNFALSE}. The routines \code{N\_VDestroy\_Petsc()} and @@ -28656,7 +28706,7 @@ \subsection{NVECTOR\_PETSC functions} \code{SUNFALSE}. In such a case, it is the user's responsibility to deallocate the \code{pvec} pointer. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_PETSC implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representations of these vectors. It is @@ -29003,13 +29053,13 @@ \subsection{NVECTOR\_CUDA functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When there is a need to access components of an \code{N\_Vector\_Cuda}, \code{v}, it is recommeded to use functions {\hyperref[nvectors/NVector_CUDA:c.N_VGetDeviceArrayPointer_Cuda]{\emph{\code{N\_VGetDeviceArrayPointer\_Cuda()}}}} or {\hyperref[nvectors/NVector_CUDA:c.N_VGetHostArrayPointer_Cuda]{\emph{\code{N\_VGetHostArrayPointer\_Cuda()}}}}. However, when using managed memory, the function {\hyperref[nvectors/NVector_Operations:c.N_VGetArrayPointer]{\emph{\code{N\_VGetArrayPointer()}}}} may also be used. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_CUDA implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representations of these vectors. It is the user's @@ -29271,12 +29321,12 @@ \subsection{NVECTOR\_RAJA functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When there is a need to access components of an \code{N\_Vector\_Raja}, \code{v}, it is recommeded to use functions {\hyperref[nvectors/NVector_RAJA:c.N_VGetDeviceArrayPointer_Raja]{\emph{\code{N\_VGetDeviceArrayPointer\_Raja()}}}} or {\hyperref[nvectors/NVector_RAJA:c.N_VGetHostArrayPointer_Raja]{\emph{\code{N\_VGetHostArrayPointer\_Raja()}}}}. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_RAJA implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representations of these vectors. It is the user's @@ -29648,20 +29698,20 @@ \subsection{NVECTOR\_OPENMPDEV functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of an \code{N\_Vector} \code{v}, it is most efficient to first obtain the component array via \code{h\_data = NV\_DATA\_HOST\_OMPDEV(v)} for the host arry or \code{v\_data = NV\_DATA\_DEV\_OMPDEV(v)} for the device array and then access \code{v\_data{[}i{]}} within the loop. -\item {} +\item {} When accessing individual components of an \code{N\_Vector} \code{v} on the host remember to first copy the array back from the device with \code{N\_VCopyFromDevice\_OpenMPDEV(v)} to ensure the array is up to date. -\item {} +\item {} \code{N\_VNewEmpty\_OpenMPDEV()}, \code{N\_VMake\_OpenMPDEV()}, and \code{N\_VCloneVectorArrayEmpty\_OpenMPDEV()} set the field \emph{own\_data} to \code{SUNFALSE}. The functions \code{N\_VDestroy\_OpenMPDEV()} and @@ -29670,7 +29720,7 @@ \subsection{NVECTOR\_OPENMPDEV functions} In such a case, it is the user's responsibility to deallocate the data pointers. -\item {} +\item {} To maximize efficiency, vector operations in the NVECTOR\_OPENMPDEV implementation that have more than one \code{N\_Vector} argument do not check for consistent internal representation of these vectors. It is @@ -29765,7 +29815,7 @@ \subsection{NVECTOR\_TRILINOS functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} The template parameter \code{vector\_type} should be set as: \begin{Verbatim}[commandchars=\\\{\}] @@ -29775,13 +29825,13 @@ \subsection{NVECTOR\_TRILINOS functions} This will ensure that data types used in Tpetra vector match those in SUNDIALS. -\item {} +\item {} When there is a need to access components of an \code{N\_Vector\_Trilinos}, \code{v}, it is recommeded to extract the Trilinos vector object via \code{x\_vec = N\_VGetVector\_Trilinos(v)} and then access components using the appropriate Trilinos functions. -\item {} +\item {} The functions \code{N\_VDestroy\_Trilinos} and \code{N\_VDestroyVectorArray\_Trilinos} only delete the \code{N\_Vector} wrapper. The underlying Tpetra vector object will exist for as long @@ -29800,7 +29850,7 @@ \section{The NVECTOR\_MANYVECTOR Module} together to form the NVECTOR\_MANYVECTOR. We envision two generic use cases for this implementation: \begin{enumerate} -\item {} +\item {} \emph{Heterogenous computational architectures}: for users who wish to partition data on a node between different computing resources, they may create architecture-specific @@ -29809,7 +29859,7 @@ \section{The NVECTOR\_MANYVECTOR Module} GPU accelerators based on NVECTOR\_CUDA, and another threaded component based on NVECTOR\_OPENMP. -\item {} +\item {} \emph{Structure of arrays (SOA) data layouts}: for users who wish to create separate subvectors for each solution component, e.g., in a Navier-Stokes simulation they @@ -30072,7 +30122,7 @@ \subsection{NVECTOR\_MANYVECTOR functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} {\hyperref[nvectors/NVector_ManyVector:c.N_VNew_ManyVector]{\emph{\code{N\_VNew\_ManyVector()}}}} sets the field \code{own\_data = SUNFALSE}. \code{N\_VDestroy\_ManyVector()} will not attempt to call @@ -30081,7 +30131,7 @@ \subsection{NVECTOR\_MANYVECTOR functions} \code{SUNFALSE}. In such a case, it is the user's responsibility to deallocate the subvectors. -\item {} +\item {} To maximize efficiency, arithmetic vector operations in the NVECTOR\_MANYVECTOR implementation that have more than one \code{N\_Vector} argument do not check for consistent internal @@ -30106,7 +30156,7 @@ \section{The NVECTOR\_MPIMANYVECTOR Module} the NVECTOR\_MPIMANYVECTOR. We envision three generic use cases for this implementation: \begin{enumerate} -\item {} +\item {} \emph{Heterogenous computational architectures (single-node or multi-node)}: for users who wish to partition data on a node between different computing resources, they may create architecture-specific @@ -30116,7 +30166,7 @@ \section{The NVECTOR\_MPIMANYVECTOR Module} and another threaded single-node component based on NVECTOR\_OPENMP. -\item {} +\item {} \emph{Process-based multiphysics decompositions (multi-node)}: for users who wish to combine separate simulations together, e.g., where one subvector resides on one subset of MPI processes, while @@ -30124,7 +30174,7 @@ \section{The NVECTOR\_MPIMANYVECTOR Module} and where the user has created a MPI \emph{intercommunicator} to connect these distinct process sets together. -\item {} +\item {} \emph{Structure of arrays (SOA) data layouts (single-node or multi-node)}: for users who wish to create separate subvectors for each solution component, e.g., in a Navier-Stokes simulation they @@ -30440,7 +30490,7 @@ \subsection{NVECTOR\_MPIMANYVECTOR functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} {\hyperref[nvectors/NVector_MPIManyVector:c.N_VNew_MPIManyVector]{\emph{\code{N\_VNew\_MPIManyVector()}}}} and {\hyperref[nvectors/NVector_MPIManyVector:c.N_VMake_MPIManyVector]{\emph{\code{N\_VMake\_MPIManyVector()}}}} set the field \code{own\_data = SUNFALSE}. \code{N\_VDestroy\_MPIManyVector()} will not attempt to call @@ -30449,7 +30499,7 @@ \subsection{NVECTOR\_MPIMANYVECTOR functions} \code{SUNFALSE}. In such a case, it is the user's responsibility to deallocate the subvectors. -\item {} +\item {} To maximize efficiency, arithmetic vector operations in the NVECTOR\_MPIMANYVECTOR implementation that have more than one \code{N\_Vector} argument do not check for consistent internal @@ -30570,13 +30620,13 @@ \subsection{NVECTOR\_MPIPLUSX functions} \textbf{Notes} \begin{itemize} -\item {} +\item {} {\hyperref[nvectors/NVector_MPIPlusX:c.N_VMake_MPIPlusX]{\emph{\code{N\_VMake\_MPIPlusX()}}}} sets the field \code{own\_data = SUNFALSE} and \code{N\_VDestroy\_MPIPlusX()} will not call {\hyperref[nvectors/NVector_Operations:c.N_VDestroy]{\emph{\code{N\_VDestroy()}}}} on the local vector. In this a case, it is the user's responsibility to deallocate the local vector. -\item {} +\item {} To maximize efficiency, arithmetic vector operations in the NVECTOR\_MPIPLUSX implementation that have more than one \code{N\_Vector} argument do not check for consistent internal @@ -30598,307 +30648,307 @@ \section{NVECTOR Examples} The following is a list of the example functions in \code{test\_nvector.c}: \begin{itemize} -\item {} +\item {} \code{Test\_N\_VClone}: Creates clone of vector and checks validity of clone. -\item {} +\item {} \code{Test\_N\_VCloneEmpty}: Creates clone of empty vector and checks validity of clone. -\item {} +\item {} \code{Test\_N\_VCloneVectorArray}: Creates clone of vector array and checks validity of cloned array. -\item {} +\item {} \code{Test\_N\_VCloneVectorArray}: Creates clone of empty vector array and checks validity of cloned array. -\item {} +\item {} \code{Test\_N\_VGetArrayPointer}: Get array pointer. -\item {} +\item {} \code{Test\_N\_VSetArrayPointer}: Allocate new vector, set pointer to new vector array, and check values. -\item {} +\item {} \code{Test\_N\_VGetLength}: Compares self-reported length to calculated length. -\item {} +\item {} \code{Test\_N\_VGetCommunicator}: Compares self-reported communicator to the one used in constructor; or for MPI-unaware vectors it ensures that NULL is reported. -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 1a: Test y = x + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 1b: Test y = -x + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 1c: Test y = ax + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 2a: Test x = x + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 2b: Test x = x - y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 2c: Test x = x + by -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 3: Test z = x + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 4a: Test z = x - y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 4b: Test z = -x + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 5a: Test z = x + by -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 5b: Test z = ax + y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 6a: Test z = -x + by -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 6b: Test z = ax - y -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 7: Test z = a(x + y) -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 8: Test z = a(x - y) -\item {} +\item {} \code{Test\_N\_VLinearSum} Case 9: Test z = ax + by -\item {} +\item {} \code{Test\_N\_VConst}: Fill vector with constant and check result. -\item {} +\item {} \code{Test\_N\_VProd}: Test vector multiply: z = x * y -\item {} +\item {} \code{Test\_N\_VDiv}: Test vector division: z = x / y -\item {} +\item {} \code{Test\_N\_VScale}: Case 1: scale: x = cx -\item {} +\item {} \code{Test\_N\_VScale}: Case 2: copy: z = x -\item {} +\item {} \code{Test\_N\_VScale}: Case 3: negate: z = -x -\item {} +\item {} \code{Test\_N\_VScale}: Case 4: combination: z = cx -\item {} +\item {} \code{Test\_N\_VAbs}: Create absolute value of vector. -\item {} +\item {} \code{Test\_N\_VAddConst}: add constant vector: z = c + x -\item {} +\item {} \code{Test\_N\_VDotProd}: Calculate dot product of two vectors. -\item {} +\item {} \code{Test\_N\_VMaxNorm}: Create vector with known values, find and validate the max norm. -\item {} +\item {} \code{Test\_N\_VWrmsNorm}: Create vector of known values, find and validate the weighted root mean square. -\item {} +\item {} \code{Test\_N\_VWrmsNormMask}: Create vector of known values, find and validate the weighted root mean square using all elements except one. -\item {} +\item {} \code{Test\_N\_VMin}: Create vector, find and validate the min. -\item {} +\item {} \code{Test\_N\_VWL2Norm}: Create vector, find and validate the weighted Euclidean L2 norm. -\item {} +\item {} \code{Test\_N\_VL1Norm}: Create vector, find and validate the L1 norm. -\item {} +\item {} \code{Test\_N\_VCompare}: Compare vector with constant returning and validating comparison vector. -\item {} +\item {} \code{Test\_N\_VInvTest}: Test z{[}i{]} = 1 / x{[}i{]} -\item {} +\item {} \code{Test\_N\_VConstrMask}: Test mask of vector x with vector c. -\item {} +\item {} \code{Test\_N\_VMinQuotient}: Fill two vectors with known values. Calculate and validate minimum quotient. -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 1a: Test x = a x -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 1b: Test z = a x -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 2a: Test x = a x + b y -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 2b: Test z = a x + b y -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 3a: Test x = x + a y + b z -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 3b: Test x = a x + b y + c z -\item {} +\item {} \code{Test\_N\_VLinearCombination}: Case 3c: Test w = a x + b y + c z -\item {} +\item {} \code{Test\_N\_VScaleAddMulti}: Case 1a: y = a x + y -\item {} +\item {} \code{Test\_N\_VScaleAddMulti}: Case 1b: z = a x + y -\item {} +\item {} \code{Test\_N\_VScaleAddMulti}: Case 2a: Y{[}i{]} = c{[}i{]} x + Y{[}i{]}, i = 1,2,3 -\item {} +\item {} \code{Test\_N\_VScaleAddMulti}: Case 2b: Z{[}i{]} = c{[}i{]} x + Y{[}i{]}, i = 1,2,3 -\item {} +\item {} \code{Test\_N\_VDotProdMulti}: Case 1: Calculate the dot product of two vectors -\item {} +\item {} \code{Test\_N\_VDotProdMulti}: Case 2: Calculate the dot product of one vector with three other vectors in a vector array. -\item {} +\item {} \code{Test\_N\_VLinearSumVectorArray}: Case 1: z = a x + b y -\item {} +\item {} \code{Test\_N\_VLinearSumVectorArray}: Case 2a: Z{[}i{]} = a X{[}i{]} + b Y{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearSumVectorArray}: Case 2b: X{[}i{]} = a X{[}i{]} + b Y{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearSumVectorArray}: Case 2c: Y{[}i{]} = a X{[}i{]} + b Y{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 1a: y = c y -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 1b: z = c y -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 2a: Y{[}i{]} = c{[}i{]} Y{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 2b: Z{[}i{]} = c{[}i{]} Y{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 1a: z = c -\item {} +\item {} \code{Test\_N\_VScaleVectorArray}: Case 1b: Z{[}i{]} = c -\item {} +\item {} \code{Test\_N\_VWrmsNormVectorArray}: Case 1a: Create a vector of know values, find and validate the weighted root mean square norm. -\item {} +\item {} \code{Test\_N\_VWrmsNormVectorArray}: Case 1b: Create a vector array of three vectors of know values, find and validate the weighted root mean square norm of each. -\item {} +\item {} \code{Test\_N\_VWrmsNormMaskVectorArray}: Case 1a: Create a vector of know values, find and validate the weighted root mean square norm using all elements except one. -\item {} +\item {} \code{Test\_N\_VWrmsNormMaskVectorArray}: Case 1b: Create a vector array of three vectors of know values, find and validate the weighted root mean square norm of each using all elements except one. -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 1a: y = a x + y -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 1b: z = a x + y -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 2a: Y{[}j{]}{[}0{]} = a{[}j{]} X{[}0{]} + Y{[}j{]}{[}0{]} -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 2b: Z{[}j{]}{[}0{]} = a{[}j{]} X{[}0{]} + Y{[}j{]}{[}0{]} -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 3a: Y{[}0{]}{[}i{]} = a{[}0{]} X{[}i{]} + Y{[}0{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 3b: Z{[}0{]}{[}i{]} = a{[}0{]} X{[}i{]} + Y{[}0{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 4a: Y{[}j{]}{[}i{]} = a{[}j{]} X{[}i{]} + Y{[}j{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VScaleAddMultiVectorArray}: Case 4b: Z{[}j{]}{[}i{]} = a{[}j{]} X{[}i{]} + Y{[}j{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 1a: x = a x -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 1b: z = a x -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 2a: x = a x + b y -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 2b: z = a x + b y -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 3a: x = a x + b y + c z -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 3b: w = a x + b y + c z -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 4a: X{[}0{]}{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 4b: Z{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 5a: X{[}0{]}{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} + c{[}1{]} X{[}1{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 5b: Z{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} + c{[}1{]} X{[}1{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 6a: X{[}0{]}{[}i{]} = X{[}0{]}{[}i{]} + c{[}1{]} X{[}1{]}{[}i{]} + c{[}2{]} X{[}2{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 6b: X{[}0{]}{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} + c{[}1{]} X{[}1{]}{[}i{]} + c{[}2{]} X{[}2{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VLinearCombinationVectorArray}: Case 6c: Z{[}i{]} = c{[}0{]} X{[}0{]}{[}i{]} + c{[}1{]} X{[}1{]}{[}i{]} + c{[}2{]} X{[}2{]}{[}i{]} -\item {} +\item {} \code{Test\_N\_VDotProdLocal}: Calculate MPI task-local portion of the dot product of two vectors. -\item {} +\item {} \code{Test\_N\_VMaxNormLocal}: Create vector with known values, find and validate the MPI task-local portion of the max norm. -\item {} +\item {} \code{Test\_N\_VMinLocal}: Create vector, find and validate the MPI task-local min. -\item {} +\item {} \code{Test\_N\_VL1NormLocal}: Create vector, find and validate the MPI task-local portion of the L1 norm. -\item {} +\item {} \code{Test\_N\_VWSqrSumLocal}: Create vector of known values, find and validate the MPI task-local portion of the weighted squared sum of two vectors. -\item {} +\item {} \code{Test\_N\_VWSqrSumMaskLocal}: Create vector of known values, find and validate the MPI task-local portion of the weighted squared sum of two vectors, using all elements except one. -\item {} +\item {} \code{Test\_N\_VInvTestLocal}: Test the MPI task-local portion of z{[}i{]} = 1 / x{[}i{]} -\item {} +\item {} \code{Test\_N\_VConstrMaskLocal}: Test the MPI task-local portion of the mask of vector x with vector c. -\item {} +\item {} \code{Test\_N\_VMinQuotientLocal}: Fill two vectors with known values. Calculate and validate the MPI task-local minimum quotient. \end{itemize} @@ -30940,220 +30990,220 @@ \section{NVECTOR functions required by ARKode} \begin{tabulary}{\linewidth}{|L|L|L|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Routine -} & \textsf{\relax +} & \textsf{\relax ARKSTEP -} & \textsf{\relax +} & \textsf{\relax ERKSTEP -} & \textsf{\relax +} & \textsf{\relax ARKLS -} & \textsf{\relax +} & \textsf{\relax ARKBANDPRE -} & \textsf{\relax +} & \textsf{\relax ARKBBDPRE -} & \textsf{\relax +} & \textsf{\relax FARKODE }\\ \hline N\_VGetLength - & & & + & & & X & & & \\ \hline N\_VAbs - & + & X - & + & X & & & & \\ \hline N\_VAddConst - & + & X - & + & X & & & & \\ \hline N\_VClone - & + & X - & + & X - & + & X & & & \\ \hline N\_VCloneEmpty - & & & & & & + & & & & & & X \\ \hline N\_VConst - & + & X - & + & X - & + & X - & & & + & & & X \\ \hline N\_VDestroy - & + & X - & + & X - & + & X - & & & + & & & X \\ \hline N\_VDiv - & + & X - & + & X & & & & \\ \hline N\_VGetArrayPointer - & & & + & & & X$^{\text{1}}$ - & + & X - & + & X - & + & X \\ \hline N\_VInv - & + & X - & + & X & & & & \\ \hline N\_VLinearSum - & + & X - & + & X - & + & X & & & \\ \hline N\_VMaxNorm - & + & X - & + & X & & & & \\ \hline N\_VMin - & + & X - & + & X - & & & & + & & & & X \\ \hline N\_VScale - & + & X - & + & X - & + & X - & + & X - & + & X & \\ \hline N\_VSetArrayPointer - & & & + & & & X$^{\text{1}}$ - & & & + & & & X \\ \hline N\_VSpace$^{\text{2}}$ - & + & X - & + & X - & + & X - & + & X - & + & X & \\ \hline N\_VWrmsNorm - & + & X - & + & X - & + & X - & + & X - & + & X & \\ \hline N\_VLinearCombination$^{\text{3}}$ - & + & X - & + & X & & & & \\ \hline N\_VMinQuotient$^{\text{5}}$ - & + & X - & + & X & & & & \\ \hline N\_VConstrMask$^{\text{5}}$ - & + & X - & + & X & & & & \\ \hline N\_VCompare$^{\text{5}}$ - & + & X - & + & X & & & & \\ \hline\end{tabulary} \begin{enumerate} -\item {} +\item {} This is only required with dense or band matrix-based linear solver modules, where the default difference-quotient Jacobian approximation is used. -\item {} +\item {} The {\hyperref[nvectors/NVector_Operations:c.N_VSpace]{\emph{\code{N\_VSpace()}}}} function is only informational, and will only be called if provided by the \code{N\_Vector} implementation. -\item {} +\item {} The {\hyperref[nvectors/NVector_Operations:c.N_VLinearCombination]{\emph{\code{N\_VLinearCombination()}}}} function is in fact optional; if it is not supplied then {\hyperref[nvectors/NVector_Operations:c.N_VLinearSum]{\emph{\code{N\_VLinearSum()}}}} will be used instead. -\item {} +\item {} The {\hyperref[nvectors/NVector_Operations:c.N_VGetLength]{\emph{\code{N\_VGetLength()}}}} function is only required when an iterative or matrix iterative \code{SUNLinearSolver} module is used. -\item {} +\item {} The functions {\hyperref[nvectors/NVector_Operations:c.N_VMinQuotient]{\emph{\code{N\_VMinQuotient()}}}}, {\hyperref[nvectors/NVector_Operations:c.N_VConstrMask]{\emph{\code{N\_VConstrMask()}}}}, and {\hyperref[nvectors/NVector_Operations:c.N_VCompare]{\emph{\code{N\_VCompare()}}}} are only used when inequality constraints are enabled and may be omitted if this feature is not used. @@ -31247,10 +31297,10 @@ \section{Description of the SUNMATRIX Modules} matrix operations defined by the generic SUNMATRIX module. A particular implementation of the SUNMATRIX module must: \begin{itemize} -\item {} +\item {} Specify the \emph{content} field of the \code{SUNMatrix} object. -\item {} +\item {} Define and implement a minimal subset of the matrix operations. See the documentation for each SUNDIALS solver to determine which SUNMATRIX operations they require. The list of required @@ -31262,17 +31312,17 @@ \section{Description of the SUNMATRIX Modules} module (each with different \code{SUNMatrix} internal data representations) in the same code. -\item {} +\item {} Define and implement user-callable constructor and destructor routines to create and free a \code{SUNMatrix} with the new \emph{content} field and with \emph{ops} pointing to the new matrix operations. -\item {} +\item {} Optionally, define and implement additional user-callable routines acting on the newly defined \code{SUNMatrix} (e.g., a routine to print the \emph{content} for debugging purposes). -\item {} +\item {} Optionally, provide accessor macros as needed for that particular implementation to be used to access different parts in the content field of the newly defined \code{SUNMatrix}. @@ -31307,10 +31357,10 @@ \section{Description of the SUNMATRIX Modules} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{A} -- the matrix to copy operations from. -\item {} +\item {} \emph{B} -- the matrix to copy operations to. \end{itemize} @@ -31335,7 +31385,7 @@ \section{Description of the SUNMATRIX Modules} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{A} -- a SUNMatrix object \end{itemize} @@ -31356,46 +31406,46 @@ \subsection{Identifiers associated with matrix kernels supplied with SUNDIALS} \label{sunmatrix/SUNMatrix_Description:sunmatrix-matrixids}\label{sunmatrix/SUNMatrix_Description:identifiers-associated-with-matrix-kernels-supplied-with-sundials} \begin{tabulary}{\linewidth}{|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Matrix ID -} & \textsf{\relax +} & \textsf{\relax Matrix type -} & \textsf{\relax +} & \textsf{\relax ID Value }\\ \hline SUNMATRIX\_DENSE - & + & Dense \(M\times N\) matrix - & + & 0 \\ \hline SUNMATRIX\_BAND - & + & Band \(M\times M\) matrix - & + & 1 \\ \hline SUNMATRIX\_SPARSE - & + & Sparse (CSR or CSC) \(M\times N\) matrix - & + & 2 \\ \hline SUNMATRIX\_SLUNRLOC - & + & SUNMatrix wrapper for SuperLU\_DIST SuperMatrix - & + & 3 \\ \hline SUNMATRIX\_CUSTOM - & + & User-provided custom matrix - & + & 4 \\ \hline\end{tabulary} @@ -31591,19 +31641,19 @@ \subsection{SUNMatrix return codes} common pattern: 0 indicates success, a negative value indicates a failure. Aside from this pattern, the actual values of each error code are primarily to provide additional information to the user in case of a SUNMatrix failure. \begin{itemize} -\item {} +\item {} \code{SUNMAT\_SUCCESS} (0) -- successful call -\item {} +\item {} \code{SUNMAT\_ILL\_INPUT} (-1) -- an illegal input has been provided to the function -\item {} +\item {} \code{SUNMAT\_MEM\_FAIL} (-2) -- failed memory access or allocation -\item {} +\item {} \code{SUNMAT\_OPERATION\_FAIL} (-3) -- a SUNMatrix operation returned nonzero -\item {} +\item {} \code{SUNMAT\_MATVEC\_SETUP\_REQUIRED} (-4) -- the \code{SUNMatMatvecSetup} routine needs to be called prior to calling \code{SUNMatMatvec} @@ -31627,96 +31677,96 @@ \subsection{SUNDIALS matrix interfaces and vector implementations that can be us \label{sunmatrix/SUNMatrix_Compatibility:sunmatrix-matrix-vector}\label{sunmatrix/SUNMatrix_Compatibility:sundials-matrix-interfaces-and-vector-implementations-that-can-be-used-for-each} \begin{tabulary}{\linewidth}{|L|L|L|L|L|L|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Linear Solver -} & \textsf{\relax +} & \textsf{\relax Serial -} & \textsf{\relax +} & \textsf{\relax Parallel (MPI) -} & \textsf{\relax +} & \textsf{\relax OpenMP -} & \textsf{\relax +} & \textsf{\relax pThreads -} & \textsf{\relax +} & \textsf{\relax \emph{hypre} Vec. -} & \textsf{\relax +} & \textsf{\relax PETSc Vec. -} & \textsf{\relax +} & \textsf{\relax CUDA -} & \textsf{\relax +} & \textsf{\relax RAJA -} & \textsf{\relax +} & \textsf{\relax User Suppl. }\\ \hline Dense - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline Band - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline Sparse - & + & X - & & + & & X - & + & X - & & & & & + & & & & & X \\ \hline SLUNRloc - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & & & + & & & X \\ \hline User supplied - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X - & + & X \\ \hline\end{tabulary} @@ -31741,23 +31791,23 @@ \section{The SUNMATRIX\_DENSE Module} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{M} - number of rows -\item {} +\item {} \code{N} - number of columns -\item {} +\item {} \code{data} - pointer to a contiguous block of \code{realtype} variables. The elements of the dense matrix are stored columnwise, i.e. the \(A_{i,j}\) element of a dense \code{SUNMatrix A} (with \(0 \le i < M\) and \(0 \le j < N\)) may be accessed via \code{data{[}j*M+i{]}}. -\item {} +\item {} \code{ldata} - length of the data array (\(= M \cdot N\)). -\item {} +\item {} \code{cols} - array of pointers. \code{cols{[}j{]}} points to the first element of the j-th column of the matrix in the array \code{data}. The \(A_{i,j}\) element of a dense \code{SUNMatrix A} @@ -32014,21 +32064,21 @@ \section{The SUNMATRIX\_DENSE Module} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of a dense \code{SUNMatrix A}, the most efficient approaches are to: \begin{itemize} -\item {} +\item {} First obtain the component array via \code{A\_data = SM\_DATA\_D(A)} or \code{A\_data = SUNDenseMatrix\_Data(A)} and then access \code{A\_data{[}i{]}} within the loop. -\item {} +\item {} First obtain the array of column pointers via \code{A\_cols = SM\_COLS\_D(A)} or \code{A\_cols = SUNDenseMatrix\_Cols(A)}, and then access \code{A\_cols{[}j{]}{[}i{]}} within the loop. -\item {} +\item {} Within a loop over the columns, access the column pointer via \code{A\_colj = SUNDenseMatrix\_Column(A,j)} and then to access the entries within that column using \code{A\_colj{[}i{]}} within the loop. @@ -32038,7 +32088,7 @@ \section{The SUNMATRIX\_DENSE Module} All three of these are more efficient than using \code{SM\_ELEMENT\_D(A,i,j)} within a double loop. -\item {} +\item {} Within the \code{SUNMatMatvec\_Dense} routine, internal consistency checks are performed to ensure that the matrix is called with consistent \code{N\_Vector} implementations. These are currently @@ -32059,17 +32109,17 @@ \section{The SUNMATRIX\_DENSE Module} Initializes a dense \code{SUNMatrix} structure for use in a SUNDIALS solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{M} (\code{long int}, input) -- number of matrix rows. -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix columns. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -32090,13 +32140,13 @@ \section{The SUNMATRIX\_DENSE Module} matrix in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{M} (\code{long int}, input) -- number of matrix rows. -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix columns. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -32131,19 +32181,19 @@ \section{The SUNMATRIX\_BAND Module} shown in Figure {\hyperref[sunmatrix/SUNMatrix_Band:sunbandmatrix]{\emph{\DUspan{}{SUNBandMatrix Diagram}}}}. A more complete description of the parts of this \emph{content} field is given below: \begin{itemize} -\item {} +\item {} \code{M} - number of rows -\item {} +\item {} \code{N} - number of columns (\code{N} = \code{M}) -\item {} +\item {} \code{mu} - upper half-bandwidth, \(0 \le \text{mu} < N\) -\item {} +\item {} \code{ml} - lower half-bandwidth, \(0 \le \text{ml} < N\) -\item {} +\item {} \code{smu} - storage upper bandwidth, \(\text{mu} \le \text{smu} < N\). The LU decomposition routines in the associated SUNLINSOL\_BAND and SUNLINSOL\_LAPACKBAND modules write the LU factors into the @@ -32152,10 +32202,10 @@ \section{The SUNMATRIX\_BAND Module} \code{min(N-1, mu+ml)} because of partial pivoting. The \code{smu} field holds the upper half-bandwidth allocated for the band matrix. -\item {} +\item {} \code{ldim} - leading dimension (\(\text{ldim} \ge smu + ml + 1\)) -\item {} +\item {} \code{data} - pointer to a contiguous block of \code{realtype} variables. The elements of the banded matrix are stored columnwise (i.e. columns are stored one on top of the other in memory). Only @@ -32163,10 +32213,10 @@ \section{The SUNMATRIX\_BAND Module} is a pointer to \code{ldata} contiguous locations which hold the elements within the banded matrix. -\item {} +\item {} \code{ldata} - length of the data array (\(= \text{ldim} \cdot N\)) -\item {} +\item {} \code{cols} - array of pointers. \code{cols{[}j{]}} is a pointer to the uppermost element within the band in the j-th column. This pointer may be treated as an array indexed from @@ -32467,15 +32517,15 @@ \section{The SUNMATRIX\_BAND Module} upper bandwidth, \code{smu}. When creating a band \code{SUNMatrix}, this value should be \begin{itemize} -\item {} +\item {} at least \code{min(N-1,mu+ml)} if the matrix will be used by the SUNLinSol\_Band module; -\item {} +\item {} exactly equal to \code{mu+ml} if the matrix will be used by the SUNLinSol\_LapackBand module; -\item {} +\item {} at least \code{mu} if used in some other manner. \end{itemize} @@ -32576,21 +32626,21 @@ \section{The SUNMATRIX\_BAND Module} \textbf{Notes} \begin{itemize} -\item {} +\item {} When looping over the components of a banded \code{SUNMatrix A}, the most efficient approaches are to: \begin{itemize} -\item {} +\item {} First obtain the component array via \code{A\_data = SM\_DATA\_B(A)} or \code{A\_data = SUNBandMatrix\_Data(A)} and then access \code{A\_data{[}i{]}} within the loop. -\item {} +\item {} First obtain the array of column pointers via \code{A\_cols = SM\_COLS\_B(A)} or \code{A\_cols = SUNBandMatrix\_Cols(A)}, and then access \code{A\_cols{[}j{]}{[}i{]}} within the loop. -\item {} +\item {} Within a loop over the columns, access the column pointer via \code{A\_colj = SUNBandMatrix\_Column(A,j)} and then to access the entries within that column using \code{SM\_COLUMN\_ELEMENT\_B(A\_colj,i,j)}. @@ -32600,7 +32650,7 @@ \section{The SUNMATRIX\_BAND Module} All three of these are more efficient than using \code{SM\_ELEMENT\_B(A,i,j)} within a double loop. -\item {} +\item {} Within the \code{SUNMatMatvec\_Band} routine, internal consistency checks are performed to ensure that the matrix is called with consistent \code{N\_Vector} implementations. These are currently @@ -32621,20 +32671,20 @@ \section{The SUNMATRIX\_BAND Module} Initializes a band \code{SUNMatrix} structure for use in a SUNDIALS solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix rows (and columns). -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth. -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -32655,16 +32705,16 @@ \section{The SUNMATRIX\_BAND Module} matrix in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix rows (and columns). -\item {} +\item {} \emph{MU} (\code{long int}, input) -- upper half-bandwidth. -\item {} +\item {} \emph{ML} (\code{long int}, input) -- lower half-bandwidth. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -32706,36 +32756,36 @@ \section{The SUNMATRIX\_SPARSE Module} shown in Figure {\hyperref[sunmatrix/SUNMatrix_Sparse:sunsparsematrix]{\emph{\DUspan{}{SUNSparseMatrix Diagram}}}}. A more complete description of the parts of this \emph{content} field is given below: \begin{itemize} -\item {} +\item {} \code{M} - number of rows -\item {} +\item {} \code{N} - number of columns -\item {} +\item {} \code{NNZ} - maximum number of nonzero entries in the matrix (allocated length of \code{data} and \code{indexvals} arrays) -\item {} +\item {} \code{NP} - number of index pointers (e.g. number of column pointers for CSC matrix). For CSC matrices \code{NP=N}, and for CSR matrices \code{NP=M}. This value is set automatically at construction based the input choice for \code{sparsetype}. -\item {} +\item {} \code{data} - pointer to a contiguous block of \code{realtype} variables (of length \code{NNZ}), containing the values of the nonzero entries in the matrix -\item {} +\item {} \code{sparsetype} - type of the sparse matrix (\code{CSC\_MAT} or \code{CSR\_MAT}) -\item {} +\item {} \code{indexvals} - pointer to a contiguous block of \code{int} variables (of length \code{NNZ}), containing the row indices (if CSC) or column indices (if CSR) of each nonzero matrix entry held in \code{data} -\item {} +\item {} \code{indexptrs} - pointer to a contiguous block of \code{int} variables (of length \code{NP+1}). For CSC matrices each entry provides the index of the first column entry into the \code{data} and @@ -32756,19 +32806,19 @@ \section{The SUNMATRIX\_SPARSE Module} automatically when creating a sparse \code{SUNMatrix}, based on the sparse matrix storage type. \begin{itemize} -\item {} +\item {} \code{rowvals} - pointer to \code{indexvals} when \code{sparsetype} is \code{CSC\_MAT}, otherwise set to \code{NULL}. -\item {} +\item {} \code{colptrs} - pointer to \code{indexptrs} when \code{sparsetype} is \code{CSC\_MAT}, otherwise set to \code{NULL}. -\item {} +\item {} \code{colvals} - pointer to \code{indexvals} when \code{sparsetype} is \code{CSR\_MAT}, otherwise set to \code{NULL}. -\item {} +\item {} \code{rowptrs} - pointer to \code{indexptrs} when \code{sparsetype} is \code{CSR\_MAT}, otherwise set to \code{NULL}. @@ -33047,13 +33097,13 @@ \section{The SUNMATRIX\_SPARSE Module} Requirements: \begin{itemize} -\item {} +\item {} \emph{A} must have type \code{SUNMATRIX\_DENSE} -\item {} +\item {} \emph{droptol} must be non-negative -\item {} +\item {} \emph{sparsetype} must be either \code{CSC\_MAT} or \code{CSR\_MAT} \end{itemize} @@ -33073,13 +33123,13 @@ \section{The SUNMATRIX\_SPARSE Module} Requirements: \begin{itemize} -\item {} +\item {} \emph{A} must have type \code{SUNMATRIX\_BAND} -\item {} +\item {} \emph{droptol} must be non-negative -\item {} +\item {} \emph{sparsetype} must be either \code{CSC\_MAT} or \code{CSR\_MAT}. \end{itemize} @@ -33209,24 +33259,24 @@ \section{The SUNMATRIX\_SPARSE Module} Initializes a sparse \code{SUNMatrix} structure for use in a SUNDIALS solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{M} (\code{long int}, input) -- number of matrix rows. -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix columns. -\item {} +\item {} \emph{NNZ} (\code{long int}, input) -- amount of nonzero storage to allocate. -\item {} +\item {} \emph{SPARSETYPE} (\code{int}, input) -- matrix sparsity type (\code{CSC\_MAT} or \code{CSR\_MAT}) -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -33247,20 +33297,20 @@ \section{The SUNMATRIX\_SPARSE Module} matrix in ARKode. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{M} (\code{long int}, input) -- number of matrix rows. -\item {} +\item {} \emph{N} (\code{long int}, input) -- number of matrix columns. -\item {} +\item {} \emph{NNZ} (\code{long int}, input) -- amount of nonzero storage to allocate. -\item {} +\item {} \emph{SPARSETYPE} (\code{int}, input) -- matrix sparsity type (\code{CSC\_MAT} or \code{CSR\_MAT}) -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -33294,18 +33344,18 @@ \section{The SUNMATRIX\_SLUNRLOC Module} A more complete description of the this \code{content} field is given below: \begin{itemize} -\item {} +\item {} \code{own\_data} -- a flag which indicates if the SUNMatrix is responsible for freeing \code{A\_super} -\item {} +\item {} \code{grid} -- pointer to the SuperLU\_DIST structure that stores the 2D process grid -\item {} +\item {} \code{row\_to\_proc} -- a mapping between the rows in the matrix and the process it resides on; will be \code{NULL} until the \code{SUNMatMatvecSetup} routine is called -\item {} +\item {} \code{gsmv\_comm} -- pointer to the SuperLU\_DIST structure that stores the communication information needed for matrix-vector multiplication; will be \code{NULL} until the \code{SUNMatMatvecSetup} routine is called @@ -33317,7 +33367,7 @@ \section{The SUNMATRIX\_SLUNRLOC Module} \end{description} -\item {} +\item {} \code{ACS\_super} -- a column-sorted version of the matrix needed to perform matrix-vector multiplication; will be \code{NULL} until the routine \code{SUNMatMatvecSetup} routine is called @@ -33386,23 +33436,23 @@ \subsection{SUNMATRIX\_SLUNRLOC Functions} The SUNMATRIX\_SLUNRLOC module also defines implementations of all generic \code{SUNMatrix} operations listed in Table {\hyperref[sunmatrix/SUNMatrix_Operations:sunmatrix-ops]{\emph{\DUspan{}{Description of the SUNMATRIX operations}}}}: \begin{itemize} -\item {} +\item {} \code{SUNMatGetID\_SLUNRloc} -- returns \code{SUNMATRIX\_SLUNRLOC} -\item {} +\item {} \code{SUNMatClone\_SLUNRloc} -\item {} +\item {} \code{SUNMatDestroy\_SLUNRloc} -\item {} +\item {} \code{SUNMatSpace\_SLUNRloc} -- this only returns information for the storage within the matrix interface, i.e. storage for \code{row\_to\_proc} -\item {} +\item {} \code{SUNMatZero\_SLUNRloc} -\item {} +\item {} \code{SUNMatCopy\_SLUNRloc} \item {} \begin{description} @@ -33411,16 +33461,16 @@ \subsection{SUNMATRIX\_SLUNRLOC Functions} \end{description} -\item {} +\item {} \code{SUNMatScaleAddI\_SLUNRloc} -- performs \(A = cA + I\), where the diagonal of \(A\) must be present -\item {} +\item {} \code{SUNMatMatvecSetup\_SLUNRloc} -- initializes the SuperLU\_DIST parallel communication structures needed to perform a matrix-vector product; only needs to be called before the first call to \code{SUNMatMatvec} or if the matrix changed since the last setup -\item {} +\item {} \code{SUNMatMatvec\_SLUNRloc} \end{itemize} @@ -33438,23 +33488,23 @@ \section{SUNMATRIX Examples} The following is a list of the example functions in \code{test\_sunmatrix.c}: \begin{itemize} -\item {} +\item {} \code{Test\_SUNMatGetID}: Verifies the returned matrix ID against the value that should be returned. -\item {} +\item {} \code{Test\_SUNMatClone}: Creates clone of an existing matrix, copies the data, and checks that their values match. -\item {} +\item {} \code{Test\_SUNMatZero}: Zeros out an existing matrix and checks that each entry equals 0.0. -\item {} +\item {} \code{Test\_SUNMatCopy}: Clones an input matrix, copies its data to a clone, and verifies that all values match. -\item {} +\item {} \code{Test\_SUNMatScaleAdd}: Given an input matrix \(A\) and an input identity matrix \(I\), this test clones and copies \(A\) to a new matrix \(B\), computes \(B = -B+B\), and @@ -33464,14 +33514,14 @@ \section{SUNMATRIX Examples} \(C\), computes \(D = D+I\) and \(C = C+A\) using \code{SUNMatScaleAdd}, and then verifies that \(C=D\). -\item {} +\item {} \code{Test\_SUNMatScaleAddI}: Given an input matrix \(A\) and an input identity matrix \(I\), this clones and copies \(I\) to a new matrix \(B\), computes \(B = -B+I\) using \code{SUNMatScaleAddI}, and verifies that the resulting matrix entries equal 0. -\item {} +\item {} \code{Test\_SUNMatMatvec} Given an input matrix \(A\) and input vectors \(x\) and \(y\) such that \(y=Ax\), this test has different behavior depending on whether \(A\) is square. If @@ -33484,7 +33534,7 @@ \section{SUNMATRIX Examples} \(z\), \emph{computes :math:{}`z=Ax} using \code{SUNMatMatvec}, and verifies that \(y=z\). -\item {} +\item {} \code{Test\_SUNMatSpace}: verifies that \code{SUNMatSpace} can be called, and outputs the results to \code{stdout}. @@ -33515,93 +33565,93 @@ \subsection{List of matrix functions usage by ARKode code modules} \label{sunmatrix/ARKode_requirements:list-of-matrix-functions-usage-by-arkode-code-modules}\label{sunmatrix/ARKode_requirements:sunmatrix-arkode-use} \begin{tabulary}{\linewidth}{|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Routine -} & \textsf{\relax +} & \textsf{\relax ARKLS -} & \textsf{\relax +} & \textsf{\relax ARKBANDPRE -} & \textsf{\relax +} & \textsf{\relax ARKBBDPRE }\\ \hline SUNMatGetID - & + & X & & \\ \hline SUNMatClone - & + & X & & \\ \hline SUNMatDestroy - & + & X - & + & X - & + & X \\ \hline SUNMatZero - & + & X - & + & X - & + & X \\ \hline SUNMatCopy - & + & X - & + & X - & + & X \\ \hline SUNMatScaleAddI - & + & X - & + & X - & + & X \\ \hline SUNMatScaleAdd - & + & 1 & & \\ \hline SUNMatMatvec - & + & 1 & & \\ \hline SUNMatMatvecSetup - & + & 1,2 & & \\ \hline SUNMatSpace - & + & 2 - & + & 2 - & + & 2 \\ \hline\end{tabulary} \begin{enumerate} -\item {} +\item {} These matrix functions are only used for problems involving a non-identity mass matrix. -\item {} +\item {} These matrix functions are optionally used, in that these are only called if they are implemented in the \code{SUNMatrix} module that is being used (i.e. their function pointers are non-\code{NULL}). If not @@ -33662,17 +33712,17 @@ \chapter{Description of the SUNLinearSolver module} \end{gather} and where \begin{itemize} -\item {} +\item {} \(P_1\) is the left preconditioner, -\item {} +\item {} \(P_2\) is the right preconditioner, -\item {} +\item {} \(S_1\) is a diagonal matrix of scale factors for \(P_1^{-1} b\), -\item {} +\item {} \(S_2\) is a diagonal matrix of scale factors for \(P_2 x\). \end{itemize} @@ -33758,12 +33808,12 @@ \subsection{SUNLinearSolver core functions} the abstract \code{SUNLinearSolver} interface. Returned values are one of the following: \begin{itemize} -\item {} +\item {} \code{SUNLINEARSOLVER\_DIRECT} -- \code{0}, the SUNLinSol module requires a matrix, and computes an `exact' solution to the linear system defined by that matrix. -\item {} +\item {} \code{SUNLINEARSOLVER\_ITERATIVE} -- \code{1}, the SUNLinSol module does not require a matrix (though one may be provided), and computes an inexact solution to the linear system using a matrix-free @@ -33775,7 +33825,7 @@ \subsection{SUNLinearSolver core functions} may diverge), the linear solver should check for solution convergence/accuracy as appropriate. -\item {} +\item {} \code{SUNLINEARSOLVER\_MATRIX\_ITERATIVE} -- \code{2}, the SUNLinSol module requires a matrix, and computes an inexact solution to the linear system defined by that matrix using an iterative @@ -33861,22 +33911,22 @@ \subsection{SUNLinearSolver core functions} This \emph{required} function Solves a linear system \(Ax = b\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{LS} -- a SUNLinSol object. -\item {} +\item {} \emph{A} -- a \code{SUNMatrix} object. -\item {} +\item {} \emph{x} -- a \code{N\_Vector} object containing the initial guess for the solution of the linear system, and the solution to the linear system upon return. -\item {} +\item {} \emph{b} -- a \code{N\_Vector} object containing the linear system right-hand side. -\item {} +\item {} \emph{tol} -- the desired linear solver tolerance. \end{itemize} @@ -34183,58 +34233,58 @@ \subsection{SUNLinearSolver return codes} of each error code are primarily to provide additional information to the user in case of a linear solver failure. \begin{itemize} -\item {} +\item {} \code{SUNLS\_SUCCESS} (0) -- successful call or converged solve -\item {} +\item {} \code{SUNLS\_MEM\_NULL} (-801) -- the memory argument to the function is \code{NULL} -\item {} +\item {} \code{SUNLS\_ILL\_INPUT} (-802) -- an illegal input has been provided to the function -\item {} +\item {} \code{SUNLS\_MEM\_FAIL} (-803) -- failed memory access or allocation -\item {} +\item {} \code{SUNLS\_ATIMES\_FAIL\_UNREC} (-804) -- an unrecoverable failure occurred in the \code{ATimes} routine -\item {} +\item {} \code{SUNLS\_PSET\_FAIL\_UNREC} (-805) -- an unrecoverable failure occurred in the \code{Pset} routine -\item {} +\item {} \code{SUNLS\_PSOLVE\_FAIL\_UNREC} (-806) -- an unrecoverable failure occurred in the \code{Psolve} routine -\item {} +\item {} \code{SUNLS\_PACKAGE\_FAIL\_UNREC} (-807) -- an unrecoverable failure occurred in an external linear solver package -\item {} +\item {} \code{SUNLS\_GS\_FAIL} (-808) -- a failure occurred during Gram-Schmidt orthogonalization (SPGMR/SPFGMR) -\item {} +\item {} \code{SUNLS\_QRSOL\_FAIL} (-809) -- a singular \$R\$ matrix was encountered in a QR factorization (SPGMR/SPFGMR) -\item {} +\item {} \code{SUNLS\_RES\_REDUCED} (801) -- an iterative solver reduced the residual, but did not converge to the desired tolerance -\item {} +\item {} \code{SUNLS\_CONV\_FAIL} (802) -- an iterative solver did not converge (80and the residual was not reduced) -\item {} +\item {} \code{SUNLS\_ATIMES\_FAIL\_REC} (803) -- a recoverable failure occurred in the \code{ATimes} routine -\item {} +\item {} \code{SUNLS\_PSET\_FAIL\_REC} (804) -- a recoverable failure occurred in the \code{Pset} routine -\item {} +\item {} \code{SUNLS\_PSOLVE\_FAIL\_REC} (805) -- a recoverable failure occurred in the \code{Psolve} routine -\item {} +\item {} \code{SUNLS\_PACKAGE\_FAIL\_REC} (806) -- a recoverable failure occurred in an external linear solver package -\item {} +\item {} \code{SUNLS\_QRFACT\_FAIL} (807) -- a singular matrix was encountered during a QR factorization (SPGMR/SPFGMR) -\item {} +\item {} \code{SUNLS\_LUFACT\_FAIL} (808) -- a singular matrix was encountered during a LU factorization \end{itemize} @@ -34319,68 +34369,68 @@ \subsubsection{Compatible SUNLinearSolver and SUNMatrix implementations} \label{sunlinsol/SUNLinSol_API:compatible-sunlinearsolver-and-sunmatrix-implementations}\label{sunlinsol/SUNLinSol_API:sunlinsol-linsol-matrix} \begin{tabulary}{\linewidth}{|L|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Linear Solver -} & \textsf{\relax +} & \textsf{\relax Dense -} & \textsf{\relax +} & \textsf{\relax Banded -} & \textsf{\relax +} & \textsf{\relax Sparse -} & \textsf{\relax +} & \textsf{\relax User Supplied }\\ \hline Dense - & + & X - & & & + & & & X \\ \hline LapackDense - & + & X - & & & + & & & X \\ \hline Band - & & + & & X - & & + & & X \\ \hline LapackBand - & & + & & X - & & + & & X \\ \hline KLU - & & & + & & & X - & + & X \\ \hline SuperLU\_MT - & & & + & & & X - & + & X \\ \hline User supplied - & + & X - & + & X - & + & X - & + & X \\ \hline\end{tabulary} @@ -34391,10 +34441,10 @@ \subsection{Implementing a custom SUNLinearSolver module} \label{sunlinsol/SUNLinSol_API:sunlinsol-custom}\label{sunlinsol/SUNLinSol_API:implementing-a-custom-sunlinearsolver-module} A particular implementation of the \code{SUNLinearSolver} module must: \begin{itemize} -\item {} +\item {} Specify the \emph{content} field of the SUNLinSol module. -\item {} +\item {} Define and implement the required linear solver operations. See the section {\hyperref[sunlinsol/ARKode_requirements:sunlinsol-arkode]{\emph{\DUspan{}{ARKode SUNLinearSolver interface}}}} to determine which SUNLinSol operations are required for this SUNDIALS package. @@ -34404,7 +34454,7 @@ \subsection{Implementing a custom SUNLinearSolver module} SUNLinSol module (each with different \code{SUNLinearSolver} internal data representations) in the same code. -\item {} +\item {} Define and implement user-callable constructor and destructor routines to create and free a \code{SUNLinearSolver} with the new \emph{content} field and with \emph{ops} pointing to the @@ -34448,7 +34498,7 @@ \subsection{Implementing a custom SUNLinearSolver module} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{LS} -- a SUNLinearSolver object \end{itemize} @@ -34461,13 +34511,13 @@ \subsection{Implementing a custom SUNLinearSolver module} Additionally, a \code{SUNLinearSolver} implementation \emph{may} do the following: \begin{itemize} -\item {} +\item {} Define and implement additional user-callable ``set'' routines acting on the \code{SUNLinearSolver}, e.g., for setting various configuration options to tune the linear solver to a particular problem. -\item {} +\item {} Provide additional user-callable ``get'' routines acting on the \code{SUNLinearSolver} object, e.g., for returning various solve statistics. @@ -34596,23 +34646,23 @@ \section{ARKode SUNLinearSolver interface} only called if they are non-\code{NULL} in the \code{SUNLinearSolver} implementation that is being used. Note: \begin{enumerate} -\item {} +\item {} {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolNumIters]{\emph{\code{SUNLinSolNumIters()}}}} is only used to accumulate overall iterative linear solver statistics. If it is not implemented by the \code{SUNLinearSolver} module, then ARKLS will consider all solves as requiring zero iterations. -\item {} +\item {} Although {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolResNorm]{\emph{\code{SUNLinSolResNorm()}}}} is optional, if it is not implemented by the \code{SUNLinearSolver} then ARKLS will consider all solves a being \emph{exact}. -\item {} +\item {} Although ARKLS does not call {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolLastFlag]{\emph{\code{SUNLinSolLastFlag()}}}} directly, this routine is available for users to query linear solver failure modes directly. -\item {} +\item {} Although ARKLS does not call {\hyperref[sunlinsol/SUNLinSol_API:c.SUNLinSolFree]{\emph{\code{SUNLinSolFree()}}}} directly, this routine should be available for users to call when cleaning up from a simulation. @@ -34621,90 +34671,90 @@ \section{ARKode SUNLinearSolver interface} \begin{tabulary}{\linewidth}{|L|L|L|L|} \hline -\textsf{\relax +\textsf{\relax Routine -} & \textsf{\relax +} & \textsf{\relax DIRECT -} & \textsf{\relax +} & \textsf{\relax ITERATIVE -} & \textsf{\relax +} & \textsf{\relax MATRIX\_ITERATIVE }\\ \hline SUNLinSolGetType - & + & X - & + & X - & + & X \\ \hline SUNLinSolSetATimes - & + & O - & + & X - & + & O \\ \hline SUNLinSolSetPreconditioner - & + & O - & + & O - & + & O \\ \hline SUNLinSolSetScalingVectors - & + & O - & + & O - & + & O \\ \hline SUNLinSolInitialize - & + & X - & + & X - & + & X \\ \hline SUNLinSolSetup - & + & X - & + & X - & + & X \\ \hline SUNLinSolSolve - & + & X - & + & X - & + & X \\ \hline SUNLinSolNumIters$^{\text{1}}$ - & & + & & O - & + & O \\ \hline SUNLinSolResNorm$^{\text{2}}$ - & & + & & O - & + & O \\ \hline @@ -34715,11 +34765,11 @@ \section{ARKode SUNLinearSolver interface} & & & \\ \hline SUNLinSolSpace - & + & O - & + & O - & + & O \\ \hline\end{tabulary} @@ -34780,20 +34830,20 @@ \subsection{Iterative linear solver tolerance} for this lack of functionality. To this end, the following assumptions are made: \begin{itemize} -\item {} +\item {} The units of the IVP solution and linear residual are the same (i.e., the error and residual weight vectors in section {\hyperref[Mathematics:mathematics-error-norm]{\emph{\DUspan{}{Error norms}}}} are the same); this is automatically satisfied with identity mass matrix, \(M=I\), or similar. -\item {} +\item {} All solution components have similar magnitude; hence the error weight vector \(w\) used in the WRMS norm (see the section {\hyperref[Mathematics:mathematics-error-norm]{\emph{\DUspan{}{Error norms}}}}) should satisfy the assumption \begin{gather} \begin{split}w_i \approx w_{mean},\quad \text{for}\quad i=0,\ldots,n-1.\end{split}\notag \end{gather} -\item {} +\item {} The SUNLinSol object uses a standard 2-norm to measure convergence. \end{itemize} @@ -34883,11 +34933,11 @@ \subsection{SUNLinSol\_Dense Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -34912,7 +34962,7 @@ \subsection{SUNLinSol\_Dense Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -34939,20 +34989,20 @@ \subsection{SUNLinSol\_Dense Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{N} - size of the linear system, -\item {} +\item {} \code{pivots} - index array for partial pivoting in LU factorization, -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations. \end{itemize} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The ``setup'' call performs a \(LU\) factorization with partial (row) pivoting (\(\mathcal O(N^3)\) cost), \(PA=LU\), where \(P\) is a permutation matrix, \(L\) is @@ -34961,7 +35011,7 @@ \subsection{SUNLinSol\_Dense Description} on the input SUNMATRIX\_DENSE object \(A\), with pivoting information encoding \(P\) stored in the \code{pivots} array. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored \code{pivots} array and the \(LU\) factors held in the SUNMATRIX\_DENSE object @@ -34973,29 +35023,29 @@ \subsection{SUNLinSol\_Dense Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_Dense} -\item {} +\item {} \code{SUNLinSolInitialize\_Dense} -- this does nothing, since all consistency checks are performed at solver creation. -\item {} +\item {} \code{SUNLinSolSetup\_Dense} -- this performs the \(LU\) factorization. -\item {} +\item {} \code{SUNLinSolSolve\_Dense} -- this uses the \(LU\) factors and \code{pivots} array to perform the solve. -\item {} +\item {} \code{SUNLinSolLastFlag\_Dense} -\item {} +\item {} \code{SUNLinSolSpace\_Dense} -- this only returns information for the storage \emph{within} the solver object, i.e. storage for \code{N}, \code{last\_flag}, and \code{pivots}. -\item {} +\item {} \code{SUNLinSolFree\_Dense} \end{itemize} @@ -35071,11 +35121,11 @@ \subsection{SUNLinSol\_Band Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35100,7 +35150,7 @@ \subsection{SUNLinSol\_Band Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35127,20 +35177,20 @@ \subsection{SUNLinSol\_Band Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{N} - size of the linear system, -\item {} +\item {} \code{pivots} - index array for partial pivoting in LU factorization, -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations. \end{itemize} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The ``setup'' call performs a \(LU\) factorization with partial (row) pivoting, \(PA=LU\), where \(P\) is a permutation matrix, \(L\) is a lower triangular matrix with 1's on the diagonal, and \(U\) @@ -35148,12 +35198,12 @@ \subsection{SUNLinSol\_Band Description} in-place on the input SUNMATRIX\_BAND object \(A\), with pivoting information encoding \(P\) stored in the \code{pivots} array. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored \code{pivots} array and the \(LU\) factors held in the SUNMATRIX\_BAND object. -\item {} +\item {} \(A\) must be allocated to accommodate the increase in upper bandwidth that occurs during factorization. More precisely, if \(A\) is a band matrix with upper bandwidth \code{mu} and lower bandwidth @@ -35167,29 +35217,29 @@ \subsection{SUNLinSol\_Band Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_Band} -\item {} +\item {} \code{SUNLinSolInitialize\_Band} -- this does nothing, since all consistency checks are performed at solver creation. -\item {} +\item {} \code{SUNLinSolSetup\_Band} -- this performs the \(LU\) factorization. -\item {} +\item {} \code{SUNLinSolSolve\_Band} -- this uses the \(LU\) factors and \code{pivots} array to perform the solve. -\item {} +\item {} \code{SUNLinSolLastFlag\_Band} -\item {} +\item {} \code{SUNLinSolSpace\_Band} -- this only returns information for the storage \emph{within} the solver object, i.e. storage for \code{N}, \code{last\_flag}, and \code{pivots}. -\item {} +\item {} \code{SUNLinSolFree\_Band} \end{itemize} @@ -35263,11 +35313,11 @@ \subsection{SUNLinSol\_LapackDense Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35292,7 +35342,7 @@ \subsection{SUNLinSol\_LapackDense Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35320,14 +35370,14 @@ \subsection{SUNLinSol\_LapackDense Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{N} - size of the linear system, -\item {} +\item {} \code{pivots} - index array for partial pivoting in LU factorization, -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations. @@ -35353,7 +35403,7 @@ \subsection{SUNLinSol\_LapackDense Description} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The ``setup'' call performs a \(LU\) factorization with partial (row) pivoting (\(\mathcal O(N^3)\) cost), \(PA=LU\), where \(P\) is a permutation matrix, \(L\) is @@ -35362,7 +35412,7 @@ \subsection{SUNLinSol\_LapackDense Description} on the input SUNMATRIX\_DENSE object \(A\), with pivoting information encoding \(P\) stored in the \code{pivots} array. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored \code{pivots} array and the \(LU\) factors held in the SUNMATRIX\_DENSE object @@ -35374,31 +35424,31 @@ \subsection{SUNLinSol\_LapackDense Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_LapackDense} -\item {} +\item {} \code{SUNLinSolInitialize\_LapackDense} -- this does nothing, since all consistency checks are performed at solver creation. -\item {} +\item {} \code{SUNLinSolSetup\_LapackDense} -- this calls either \code{DGETRF} or \code{SGETRF} to perform the \(LU\) factorization. -\item {} +\item {} \code{SUNLinSolSolve\_LapackDense} -- this calls either \code{DGETRS} or \code{SGETRS} to use the \(LU\) factors and \code{pivots} array to perform the solve. -\item {} +\item {} \code{SUNLinSolLastFlag\_LapackDense} -\item {} +\item {} \code{SUNLinSolSpace\_LapackDense} -- this only returns information for the storage \emph{within} the solver object, i.e. storage for \code{N}, \code{last\_flag}, and \code{pivots}. -\item {} +\item {} \code{SUNLinSolFree\_LapackDense} \end{itemize} @@ -35477,11 +35527,11 @@ \subsection{SUNLinSol\_LapackBand Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35506,7 +35556,7 @@ \subsection{SUNLinSol\_LapackBand Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35533,14 +35583,14 @@ \subsection{SUNLinSol\_LapackBand Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{N} - size of the linear system, -\item {} +\item {} \code{pivots} - index array for partial pivoting in LU factorization, -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations. @@ -35566,7 +35616,7 @@ \subsection{SUNLinSol\_LapackBand Description} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The ``setup'' call performs a \(LU\) factorization with partial (row) pivoting, \(PA=LU\), where \(P\) is a permutation matrix, \(L\) is a lower triangular matrix with 1's @@ -35575,12 +35625,12 @@ \subsection{SUNLinSol\_LapackBand Description} \(A\), with pivoting information encoding \(P\) stored in the \code{pivots} array. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored \code{pivots} array and the \(LU\) factors held in the SUNMATRIX\_BAND object. -\item {} +\item {} \(A\) must be allocated to accommodate the increase in upper bandwidth that occurs during factorization. More precisely, if \(A\) is a band matrix with upper bandwidth \code{mu} and lower @@ -35594,31 +35644,31 @@ \subsection{SUNLinSol\_LapackBand Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_LapackBand} -\item {} +\item {} \code{SUNLinSolInitialize\_LapackBand} -- this does nothing, since all consistency checks are performed at solver creation. -\item {} +\item {} \code{SUNLinSolSetup\_LapackBand} -- this calls either \code{DGBTRF} or \code{SGBTRF} to perform the \(LU\) factorization. -\item {} +\item {} \code{SUNLinSolSolve\_LapackBand} -- this calls either \code{DGBTRS} or \code{SGBTRS} to use the \(LU\) factors and \code{pivots} array to perform the solve. -\item {} +\item {} \code{SUNLinSolLastFlag\_LapackBand} -\item {} +\item {} \code{SUNLinSolSpace\_LapackBand} -- this only returns information for the storage \emph{within} the solver object, i.e. storage for \code{N}, \code{last\_flag}, and \code{pivots}. -\item {} +\item {} \code{SUNLinSolFree\_LapackBand} \end{itemize} @@ -35680,13 +35730,13 @@ \subsection{SUNLinSol\_KLU Usage} The \code{reinit\_type} argument governs the level of reinitialization. The allowed values are: \begin{enumerate} -\item {} +\item {} The Jacobian matrix will be destroyed and a new one will be allocated based on the \code{nnz} value passed to this call. New symbolic and numeric factorizations will be completed at the next solver setup. -\item {} +\item {} Only symbolic and numeric factorizations will be completed. It is assumed that the Jacobian size has not exceeded the size of \code{nnz} given in the sparse matrix provided to the original @@ -35712,13 +35762,13 @@ \subsection{SUNLinSol\_KLU Usage} the linear solve. Options for \code{ordering\_choice} are: \begin{enumerate} \setcounter{enumi}{-1} -\item {} +\item {} AMD, -\item {} +\item {} COLAMD, and -\item {} +\item {} the natural ordering. \end{enumerate} @@ -35817,11 +35867,11 @@ \subsection{SUNLinSol\_KLU Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35845,7 +35895,7 @@ \subsection{SUNLinSol\_KLU Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -35943,33 +35993,33 @@ \subsection{SUNLinSol\_KLU Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations, -\item {} +\item {} \code{first\_factorize} - flag indicating whether the factorization has ever been performed, -\item {} +\item {} \code{Symbolic} - KLU storage structure for symbolic factorization components, with underlying type \code{klu\_symbolic} or \code{klu\_l\_symbolic}, depending on whether SUNDIALS was installed with 32-bit versus 64-bit indices, respectively, -\item {} +\item {} \code{Numeric} - KLU storage structure for numeric factorization components, with underlying type \code{klu\_numeric} or \code{klu\_l\_numeric}, depending on whether SUNDIALS was installed with 32-bit versus 64-bit indices, respectively, -\item {} +\item {} \code{Common} - storage structure for common KLU solver components, with underlying type \code{klu\_common} or \code{klu\_l\_common}, depending on whether SUNDIALS was installed with 32-bit versus 64-bit indices, respectively, -\item {} +\item {} \code{klu\_solver} -- pointer to the appropriate KLU solver function (depending on whether it is using a CSR or CSC sparse matrix, and on whether SUNDIALS was installed with 32-bit or 64-bit indices). @@ -36013,12 +36063,12 @@ \subsection{SUNLinSol\_KLU Description} SUNLinSol\_KLU module is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The first time that the ``setup'' routine is called, it performs the symbolic factorization, followed by an initial numerical factorization. -\item {} +\item {} On subsequent calls to the ``setup'' routine, it calls the appropriate KLU ``refactor'' routine, followed by estimates of the numerical conditioning using the relevant ``rcond'', and if @@ -36027,12 +36077,12 @@ \subsection{SUNLinSol\_KLU Description} \(\varepsilon\) is the double-precision unit roundoff), then a new factorization is performed. -\item {} +\item {} The module includes the routine \code{SUNKLUReInit}, that can be called by the user to force a full refactorization at the next ``setup'' call. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored KLU data structures. We note that in this solve KLU operates on the native data arrays @@ -36045,33 +36095,33 @@ \subsection{SUNLinSol\_KLU Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_KLU} -\item {} +\item {} \code{SUNLinSolInitialize\_KLU} -- this sets the \code{first\_factorize} flag to 1, forcing both symbolic and numerical factorizations on the subsequent ``setup'' call. -\item {} +\item {} \code{SUNLinSolSetup\_KLU} -- this performs either a \(LU\) factorization or refactorization of the input matrix. -\item {} +\item {} \code{SUNLinSolSolve\_KLU} -- this calls the appropriate KLU solve routine to utilize the \(LU\) factors to solve the linear system. -\item {} +\item {} \code{SUNLinSolLastFlag\_KLU} -\item {} +\item {} \code{SUNLinSolSpace\_KLU} -- this only returns information for the storage within the solver \emph{interface}, i.e. storage for the integers \code{last\_flag} and \code{first\_factorize}. For additional space requirements, see the KLU documentation. -\item {} +\item {} \code{SUNLinSolFree\_KLU} \end{itemize} @@ -36216,40 +36266,40 @@ \subsection{SUNLinSol\_SuperLUDIST Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{first\_factorize} -- flag indicating whether the factorization has ever been performed, -\item {} +\item {} \code{last\_flag} -- last error return flag from internal function evaluations, -\item {} +\item {} \code{berr} -- the componentwise relative backward error of the computed solution, -\item {} +\item {} \code{grid} -- pointer to the SuperLU\_DIST structure that strores the 2D process grid -\item {} +\item {} \code{lu} -- pointer to the SuperLU\_DIST structure that stores the distributed \code{L} and \code{U} factors, -\item {} +\item {} \code{scaleperm} -- pointer to the SuperLU\_DIST structure that stores vectors describing the transformations done to the matrix \code{A}, -\item {} +\item {} \code{options} -- pointer to the SuperLU\_DIST stucture which contains options that control how the linear system is factorized and solved, -\item {} +\item {} \code{solve} -- pointer to the SuperLU\_DIST solve structure, -\item {} +\item {} \code{stat} -- pointer to the SuperLU\_DIST structure that stores information about runtime and flop count, -\item {} +\item {} \code{N} -- the number of equations in the system. \end{itemize} @@ -36283,21 +36333,21 @@ \subsection{SUNLinSol\_SuperLUDIST Description} typically have identical sparsity patterns, the SUNLinSol\_SuperLUDIST module is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The first time that the ``setup'' routine is called, it sets the SuperLU\_DIST option \code{Fact} to \code{DOFACT} so that a subsequent call to the ``solve'' routine will perform a symbolic factorization, followed by an initial numerical factorization before continuing to solve the system. -\item {} +\item {} On subsequent calls to the ``setup'' routine, it sets the SuperLU\_DIST option \code{Fact} to \code{SamePattern} so that a subsequent call to ``solve'' will perform factorization assuming the same sparsity pattern as prior, i.e. it will reuse the column permutation vector. -\item {} +\item {} If ``setup'' is called prior to the ``solve'' routine, then the ``solve'' routine will perform a symbolic factorization, followed by an initial numerical factorization before continuing to the sparse triangular @@ -36312,36 +36362,36 @@ \subsection{SUNLinSol\_SuperLUDIST Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SuperLUDIST} -\item {} +\item {} \code{SUNLinSolInitialize\_SuperLUDIST} -- this sets the \code{first\_factorize} flag to 1 and resets the internal SuperLU\_DIST statistics variables. -\item {} +\item {} \code{SUNLinSolSetup\_SuperLUDIST} -- this sets the appropriate SuperLU\_DIST options so that a subsequent solve will perform a symbolic and numerical factorization before proceeding with the triangular solves -\item {} +\item {} \code{SUNLinSolSolve\_SuperLUDIST} -- this calls the SuperLU\_DIST solve routine to perform factorization (if the setup routine was called prior) and then use the \$LU\$ factors to solve the linear system. -\item {} +\item {} \code{SUNLinSolLastFlag\_SuperLUDIST} -\item {} +\item {} \code{SUNLinSolSpace\_SuperLUDIST} -- this only returns information for the storage within the solver \emph{interface}, i.e. storage for the integers \code{last\_flag} and \code{first\_factorize}. For additional space requirements, see the SuperLU\_DIST documentation. -\item {} +\item {} \code{SUNLinSolFree\_SuperLUDIST} \end{itemize} @@ -36403,16 +36453,16 @@ \subsection{SUNLinSol\_SuperLUMT Usage} the linear solve. Options for \code{ordering\_choice} are: \begin{enumerate} \setcounter{enumi}{-1} -\item {} +\item {} natural ordering -\item {} +\item {} minimal degree ordering on \(A^TA\) -\item {} +\item {} minimal degree ordering on \(A^T+A\) -\item {} +\item {} COLAMD ordering for unsymmetric matrices \end{enumerate} @@ -36463,15 +36513,15 @@ \subsection{SUNLinSol\_SuperLUMT Usage} \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{NUM\_THREADS} (\code{int}, input) -- desired number of OpenMP/Pthreads threads to use in the factorization. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -36496,11 +36546,11 @@ \subsection{SUNLinSol\_SuperLUMT Usage} the mass \code{SUNMatrix} objects have been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NUM\_THREADS} (\code{int}, input) -- desired number of OpenMP/Pthreads threads to use in the factorization. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -36567,36 +36617,36 @@ \subsection{SUNLinSol\_SuperLUMT Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{last\_flag} - last error return flag from internal function evaluations, -\item {} +\item {} \code{first\_factorize} - flag indicating whether the factorization has ever been performed, -\item {} +\item {} \code{A, AC, L, U, B} - \code{SuperMatrix} pointers used in solve, -\item {} +\item {} \code{Gstat} - \code{GStat\_t} object used in solve, -\item {} +\item {} \code{perm\_r, perm\_c} - permutation arrays used in solve, -\item {} +\item {} \code{N} - size of the linear system, -\item {} +\item {} \code{num\_threads} - number of OpenMP/Pthreads threads to use, -\item {} +\item {} \code{diag\_pivot\_thresh} - threshold on diagonal pivoting, -\item {} +\item {} \code{ordering} - flag for which reordering algorithm to use, -\item {} +\item {} \code{options} - pointer to SuperLU\_MT options structure. \end{itemize} @@ -36633,16 +36683,16 @@ \subsection{SUNLinSol\_SuperLUMT Description} SUNLinSol\_SuperLUMT module is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} The first time that the ``setup'' routine is called, it performs the symbolic factorization, followed by an initial numerical factorization. -\item {} +\item {} On subsequent calls to the ``setup'' routine, it skips the symbolic factorization, and only refactors the input matrix. -\item {} +\item {} The ``solve'' call performs pivoting and forward and backward substitution using the stored SuperLU\_MT data structures. We note that in this solve SuperLU\_MT operates on the @@ -36655,33 +36705,33 @@ \subsection{SUNLinSol\_SuperLUMT Description} ``direct'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SuperLUMT} -\item {} +\item {} \code{SUNLinSolInitialize\_SuperLUMT} -- this sets the \code{first\_factorize} flag to 1 and resets the internal SuperLU\_MT statistics variables. -\item {} +\item {} \code{SUNLinSolSetup\_SuperLUMT} -- this performs either a \(LU\) factorization or refactorization of the input matrix. -\item {} +\item {} \code{SUNLinSolSolve\_SuperLUMT} -- this calls the appropriate SuperLU\_MT solve routine to utilize the \(LU\) factors to solve the linear system. -\item {} +\item {} \code{SUNLinSolLastFlag\_SuperLUMT} -\item {} +\item {} \code{SUNLinSolSpace\_SuperLUMT} -- this only returns information for the storage within the solver \emph{interface}, i.e. storage for the integers \code{last\_flag} and \code{first\_factorize}. For additional space requirements, see the SuperLU\_MT documentation. -\item {} +\item {} \code{SUNLinSolFree\_SuperLUMT} \end{itemize} @@ -36723,26 +36773,26 @@ \subsection{SUNLinSol\_cuSolverSp\_batchQR functions} The \code{SUNLinearSolver\_cuSolverSp\_batchQR} module defines implementations of all ``direct'' linear solver operations listed in {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_cuSolverSp\_batchQR} -\item {} +\item {} \code{SUNLinSolInitialize\_cuSolverSp\_batchQR} -- this sets the \code{first\_factorize} flag to 1 -\item {} +\item {} \code{SUNLinSolSetup\_cuSolverSp\_batchQR} -- this always copies the relevant SUNMATRIX\_SPARSE data to the GPU; if this is the first setup it will perform symbolic analysis on the system -\item {} +\item {} \code{SUNLinSolSolve\_cuSolverSp\_batchQR} -- this calls the \code{cusolverSpXcsrqrsvBatched} routine to perform factorization -\item {} +\item {} \code{SUNLinSolLastFlag\_cuSolverSp\_batchQR} -\item {} +\item {} \code{SUNLinSolFree\_cuSolverSp\_batchQR} \end{itemize} @@ -36961,18 +37011,18 @@ \subsection{SUNLinSol\_SPGMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of GMRES basis vectors to use. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -36996,14 +37046,14 @@ \subsection{SUNLinSol\_SPGMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of GMRES basis vectors to use. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -37141,63 +37191,63 @@ \subsection{SUNLinSol\_SPGMR Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{maxl} - number of GMRES basis vectors to use (default is 5), -\item {} +\item {} \code{pretype} - flag for type of preconditioning to employ (default is none), -\item {} +\item {} \code{gstype} - flag for type of Gram-Schmidt orthogonalization (default is modified Gram-Schmidt), -\item {} +\item {} \code{max\_restarts} - number of GMRES restarts to allow (default is 0), -\item {} +\item {} \code{numiters} - number of iterations from the most-recent solve, -\item {} +\item {} \code{resnorm} - final linear residual norm from the most-recent solve, -\item {} +\item {} \code{last\_flag} - last error return flag from an internal function, -\item {} +\item {} \code{ATimes} - function pointer to perform \(Av\) product, -\item {} +\item {} \code{ATData} - pointer to structure for \code{ATimes}, -\item {} +\item {} \code{Psetup} - function pointer to preconditioner setup routine, -\item {} +\item {} \code{Psolve} - function pointer to preconditioner solve routine, -\item {} +\item {} \code{PData} - pointer to structure for \code{Psetup} and \code{Psolve}, -\item {} +\item {} \code{s1, s2} - vector pointers for supplied scaling matrices (default is \code{NULL}), -\item {} +\item {} \code{V} - the array of Krylov basis vectors \(v_1, \ldots, v_{\text{maxl}+1}\), stored in \code{V{[}0{]}, ... V{[}maxl{]}}. Each \(v_i\) is a vector of type \code{N\_Vector}, -\item {} +\item {} \code{Hes} - the \((\text{maxl}+1)\times\text{maxl}\) Hessenberg matrix. It is stored row-wise so that the (i,j)th element is given by \code{Hes{[}i{]}{[}j{]}}, -\item {} +\item {} \code{givens} - a length \(2\,\text{maxl}\) array which represents the Givens rotation matrices that arise in the GMRES algorithm. These matrices are \(F_0, F_1, \ldots, F_j\), where @@ -37220,48 +37270,48 @@ \subsection{SUNLinSol\_SPGMR Description} \code{givens{[}2j{]}} \(= c_j\), \code{givens{[}2j+1{]}} \(= s_j\), -\item {} +\item {} \code{xcor} - a vector which holds the scaled, preconditioned correction to the initial guess, -\item {} +\item {} \code{yg} - a length \((\text{maxl}+1)\) array of \code{realtype} values used to hold ``short'' vectors (e.g. \(y\) and \(g\)), -\item {} +\item {} \code{vtemp} - temporary vector storage. \end{itemize} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} During construction, the \code{xcor} and \code{vtemp} arrays are cloned from a template \code{N\_Vector} that is input, and default solver parameters are set. -\item {} +\item {} User-facing ``set'' routines may be called to modify default solver parameters. -\item {} +\item {} Additional ``set'' routines are called by the SUNDIALS solver that interfaces with SUNLinSol\_SPGMR to supply the \code{ATimes}, \code{PSetup}, and \code{Psolve} function pointers and \code{s1} and \code{s2} scaling vectors. -\item {} +\item {} In the ``initialize'' call, the remaining solver data is allocated (\code{V}, \code{Hes}, \code{givens}, and \code{yg} ) -\item {} +\item {} In the ``setup'' call, any non-\code{NULL} \code{PSetup} function is called. Typically, this is provided by the SUNDIALS solver itself, that translates between the generic \code{PSetup} function and the solver-specific routine (solver-supplied or user-supplied). -\item {} +\item {} In the ``solve'' call, the GMRES iteration is performed. This will include scaling, preconditioning, and restarts if those options have been supplied. @@ -37272,43 +37322,43 @@ \subsection{SUNLinSol\_SPGMR Description} ``iterative'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SPGMR} -\item {} +\item {} \code{SUNLinSolInitialize\_SPGMR} -\item {} +\item {} \code{SUNLinSolSetATimes\_SPGMR} -\item {} +\item {} \code{SUNLinSolSetPreconditioner\_SPGMR} -\item {} +\item {} \code{SUNLinSolSetScalingVectors\_SPGMR} -\item {} +\item {} \code{SUNLinSolSetup\_SPGMR} -\item {} +\item {} \code{SUNLinSolSolve\_SPGMR} -\item {} +\item {} \code{SUNLinSolNumIters\_SPGMR} -\item {} +\item {} \code{SUNLinSolResNorm\_SPGMR} -\item {} +\item {} \code{SUNLinSolResid\_SPGMR} -\item {} +\item {} \code{SUNLinSolLastFlag\_SPGMR} -\item {} +\item {} \code{SUNLinSolSpace\_SPGMR} -\item {} +\item {} \code{SUNLinSolFree\_SPGMR} \end{itemize} @@ -37464,18 +37514,18 @@ \subsection{SUNLinSol\_SPFGMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting whether to use preconditioning: no=0, yes=1. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of FGMRES basis vectors to use. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -37499,14 +37549,14 @@ \subsection{SUNLinSol\_SPFGMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting whether to use preconditioning: no=0, yes=1. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of FGMRES basis vectors to use. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -37645,66 +37695,66 @@ \subsection{SUNLinSol\_SPFGMR Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{maxl} - number of FGMRES basis vectors to use (default is 5), -\item {} +\item {} \code{pretype} - flag for use of preconditioning (default is none), -\item {} +\item {} \code{gstype} - flag for type of Gram-Schmidt orthogonalization (default is modified Gram-Schmidt), -\item {} +\item {} \code{max\_restarts} - number of FGMRES restarts to allow (default is 0), -\item {} +\item {} \code{numiters} - number of iterations from the most-recent solve, -\item {} +\item {} \code{resnorm} - final linear residual norm from the most-recent solve, -\item {} +\item {} \code{last\_flag} - last error return flag from an internal function, -\item {} +\item {} \code{ATimes} - function pointer to perform \(Av\) product, -\item {} +\item {} \code{ATData} - pointer to structure for \code{ATimes}, -\item {} +\item {} \code{Psetup} - function pointer to preconditioner setup routine, -\item {} +\item {} \code{Psolve} - function pointer to preconditioner solve routine, -\item {} +\item {} \code{PData} - pointer to structure for \code{Psetup} and \code{Psolve}, -\item {} +\item {} \code{s1, s2} - vector pointers for supplied scaling matrices (default is \code{NULL}), -\item {} +\item {} \code{V} - the array of Krylov basis vectors \(v_1, \ldots, v_{\text{maxl}+1}\), stored in \code{V{[}0{]}, ..., V{[}maxl{]}}. Each \(v_i\) is a vector of type \code{N\_Vector}, -\item {} +\item {} \code{Z} - the array of preconditioned Krylov basis vectors \(z_1, \ldots, z_{\text{maxl}+1}\), stored in \code{Z{[}0{]}, ..., Z{[}maxl{]}}. Each \(z_i\) is a vector of type \code{N\_Vector}, -\item {} +\item {} \code{Hes} - the \((\text{maxl}+1)\times\text{maxl}\) Hessenberg matrix. It is stored row-wise so that the (i,j)th element is given by \code{Hes{[}i{]}{[}j{]}}, -\item {} +\item {} \code{givens} - a length \(2\,\text{maxl}\) array which represents the Givens rotation matrices that arise in the FGMRES algorithm. These matrices are \(F_0, F_1, \ldots, F_j\), where @@ -37727,47 +37777,47 @@ \subsection{SUNLinSol\_SPFGMR Description} \code{givens{[}2j{]}} \(= c_j\), \code{givens{[}2j+1{]}} \(= s_j\), -\item {} +\item {} \code{xcor} - a vector which holds the scaled, preconditioned correction to the initial guess, -\item {} +\item {} \code{yg} - a length \((\text{maxl}+1)\) array of \code{realtype} values used to hold ``short'' vectors (e.g. \(y\) and \(g\)), -\item {} +\item {} \code{vtemp} - temporary vector storage. \end{itemize} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} During construction, the \code{xcor} and \code{vtemp} arrays are cloned from a template \code{N\_Vector} that is input, and default solver parameters are set. -\item {} +\item {} User-facing ``set'' routines may be called to modify default solver parameters. -\item {} +\item {} Additional ``set'' routines are called by the SUNDIALS solver that interfaces with SUNLinSol\_SPFGMR to supply the \code{ATimes}, \code{PSetup}, and \code{Psolve} function pointers and \code{s1} and \code{s2} scaling vectors. -\item {} +\item {} In the ``initialize'' call, the remaining solver data is allocated (\code{V}, \code{Hes}, \code{givens}, and \code{yg} ) -\item {} +\item {} In the ``setup'' call, any non-\code{NULL} \code{PSetup} function is called. Typically, this is provided by the SUNDIALS solver itself, that translates between the generic \code{PSetup} function and the solver-specific routine (solver-supplied or user-supplied). -\item {} +\item {} In the ``solve'' call, the FGMRES iteration is performed. This will include scaling, preconditioning, and restarts if those options have been supplied. @@ -37778,43 +37828,43 @@ \subsection{SUNLinSol\_SPFGMR Description} ``iterative'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SPFGMR} -\item {} +\item {} \code{SUNLinSolInitialize\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSetATimes\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSetPreconditioner\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSetScalingVectors\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSetup\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSolve\_SPFGMR} -\item {} +\item {} \code{SUNLinSolNumIters\_SPFGMR} -\item {} +\item {} \code{SUNLinSolResNorm\_SPFGMR} -\item {} +\item {} \code{SUNLinSolResid\_SPFGMR} -\item {} +\item {} \code{SUNLinSolLastFlag\_SPFGMR} -\item {} +\item {} \code{SUNLinSolSpace\_SPFGMR} -\item {} +\item {} \code{SUNLinSolFree\_SPFGMR} \end{itemize} @@ -37944,18 +37994,18 @@ \subsection{SUNLinSol\_SPBCGS Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of SPBCGS iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -37979,14 +38029,14 @@ \subsection{SUNLinSol\_SPBCGS Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of SPBCGS iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -38093,52 +38143,52 @@ \subsection{SUNLinSol\_SPBCGS Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{maxl} - number of SPBCGS iterations to allow (default is 5), -\item {} +\item {} \code{pretype} - flag for type of preconditioning to employ (default is none), -\item {} +\item {} \code{numiters} - number of iterations from the most-recent solve, -\item {} +\item {} \code{resnorm} - final linear residual norm from the most-recent solve, -\item {} +\item {} \code{last\_flag} - last error return flag from an internal function, -\item {} +\item {} \code{ATimes} - function pointer to perform \(Av\) product, -\item {} +\item {} \code{ATData} - pointer to structure for \code{ATimes}, -\item {} +\item {} \code{Psetup} - function pointer to preconditioner setup routine, -\item {} +\item {} \code{Psolve} - function pointer to preconditioner solve routine, -\item {} +\item {} \code{PData} - pointer to structure for \code{Psetup} and \code{Psolve}, -\item {} +\item {} \code{s1, s2} - vector pointers for supplied scaling matrices (default is \code{NULL}), -\item {} +\item {} \code{r} - a \code{N\_Vector} which holds the current scaled, preconditioned linear system residual, -\item {} +\item {} \code{r\_star} - a \code{N\_Vector} which holds the initial scaled, preconditioned linear system residual, -\item {} +\item {} \code{p, q, u, Ap, vtemp} - \code{N\_Vector} used for workspace by the SPBCGS algorithm. @@ -38146,32 +38196,32 @@ \subsection{SUNLinSol\_SPBCGS Description} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} During construction all \code{N\_Vector} solver data is allocated, with vectors cloned from a template \code{N\_Vector} that is input, and default solver parameters are set. -\item {} +\item {} User-facing ``set'' routines may be called to modify default solver parameters. -\item {} +\item {} Additional ``set'' routines are called by the SUNDIALS solver that interfaces with SUNLinSol\_SPBCGS to supply the \code{ATimes}, \code{PSetup}, and \code{Psolve} function pointers and \code{s1} and \code{s2} scaling vectors. -\item {} +\item {} In the ``initialize'' call, the solver parameters are checked for validity. -\item {} +\item {} In the ``setup'' call, any non-\code{NULL} \code{PSetup} function is called. Typically, this is provided by the SUNDIALS solver itself, that translates between the generic \code{PSetup} function and the solver-specific routine (solver-supplied or user-supplied). -\item {} +\item {} In the ``solve'' call the SPBCGS iteration is performed. This will include scaling and preconditioning if those options have been supplied. @@ -38182,43 +38232,43 @@ \subsection{SUNLinSol\_SPBCGS Description} ``iterative'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SPBCGS} -\item {} +\item {} \code{SUNLinSolInitialize\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSetATimes\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSetPreconditioner\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSetScalingVectors\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSetup\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSolve\_SPBCGS} -\item {} +\item {} \code{SUNLinSolNumIters\_SPBCGS} -\item {} +\item {} \code{SUNLinSolResNorm\_SPBCGS} -\item {} +\item {} \code{SUNLinSolResid\_SPBCGS} -\item {} +\item {} \code{SUNLinSolLastFlag\_SPBCGS} -\item {} +\item {} \code{SUNLinSolSpace\_SPBCGS} -\item {} +\item {} \code{SUNLinSolFree\_SPBCGS} \end{itemize} @@ -38349,18 +38399,18 @@ \subsection{SUNLinSol\_SPTFQMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of SPTFQMR iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -38384,14 +38434,14 @@ \subsection{SUNLinSol\_SPTFQMR Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting type of preconditioning to use: none=0, left=1, right=2, both=3. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of SPTFQMR iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -38501,88 +38551,88 @@ \subsection{SUNLinSol\_SPTFQMR Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{maxl} - number of TFQMR iterations to allow (default is 5), -\item {} +\item {} \code{pretype} - flag for type of preconditioning to employ (default is none), -\item {} +\item {} \code{numiters} - number of iterations from the most-recent solve, -\item {} +\item {} \code{resnorm} - final linear residual norm from the most-recent solve, -\item {} +\item {} \code{last\_flag} - last error return flag from an internal function, -\item {} +\item {} \code{ATimes} - function pointer to perform \(Av\) product, -\item {} +\item {} \code{ATData} - pointer to structure for \code{ATimes}, -\item {} +\item {} \code{Psetup} - function pointer to preconditioner setup routine, -\item {} +\item {} \code{Psolve} - function pointer to preconditioner solve routine, -\item {} +\item {} \code{PData} - pointer to structure for \code{Psetup} and \code{Psolve}, -\item {} +\item {} \code{s1, s2} - vector pointers for supplied scaling matrices (default is \code{NULL}), -\item {} +\item {} \code{r\_star} - a \code{N\_Vector} which holds the initial scaled, preconditioned linear system residual, -\item {} +\item {} \code{q, d, v, p, u} - \code{N\_Vector} used for workspace by the SPTFQMR algorithm, -\item {} +\item {} \code{r} - array of two \code{N\_Vector} used for workspace within the SPTFQMR algorithm, -\item {} +\item {} \code{vtemp1, vtemp2, vtemp3} - temporary vector storage. \end{itemize} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} During construction all \code{N\_Vector} solver data is allocated, with vectors cloned from a template \code{N\_Vector} that is input, and default solver parameters are set. -\item {} +\item {} User-facing ``set'' routines may be called to modify default solver parameters. -\item {} +\item {} Additional ``set'' routines are called by the SUNDIALS solver that interfaces with SUNLinSol\_SPTFQMR to supply the \code{ATimes}, \code{PSetup}, and \code{Psolve} function pointers and \code{s1} and \code{s2} scaling vectors. -\item {} +\item {} In the ``initialize'' call, the solver parameters are checked for validity. -\item {} +\item {} In the ``setup'' call, any non-\code{NULL} \code{PSetup} function is called. Typically, this is provided by the SUNDIALS solver itself, that translates between the generic \code{PSetup} function and the solver-specific routine (solver-supplied or user-supplied). -\item {} +\item {} In the ``solve'' call the TFQMR iteration is performed. This will include scaling and preconditioning if those options have been supplied. @@ -38593,43 +38643,43 @@ \subsection{SUNLinSol\_SPTFQMR Description} ``iterative'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolInitialize\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSetATimes\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSetPreconditioner\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSetScalingVectors\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSetup\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSolve\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolNumIters\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolResNorm\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolResid\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolLastFlag\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolSpace\_SPTFQMR} -\item {} +\item {} \code{SUNLinSolFree\_SPTFQMR} \end{itemize} @@ -38659,10 +38709,10 @@ \section{The SUNLinSol\_PCG Module} left. Scaling is also allowed and is applied symmetrically. We denote the preconditioner and scaling matrices as follows: \begin{itemize} -\item {} +\item {} \(P\) is the preconditioner (assumed symmetric), -\item {} +\item {} \(S\) is a diagonal matrix of scale factors. \end{itemize} @@ -38812,18 +38862,18 @@ \subsection{SUNLinSol\_PCG Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, KINSOL=3, ARKode=4. -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting whether to use symmetric preconditioning: no=0, yes=1. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of PCG iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -38848,14 +38898,14 @@ \subsection{SUNLinSol\_PCG Usage} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{PRETYPE} (\code{int}, input) -- flag denoting whether to use symmetric preconditioning: no=0, yes=1. -\item {} +\item {} \emph{MAXL} (\code{int}, input) -- number of PCG iterations to allow. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). \end{itemize} @@ -38958,47 +39008,47 @@ \subsection{SUNLinSol\_PCG Description} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{maxl} - number of PCG iterations to allow (default is 5), -\item {} +\item {} \code{pretype} - flag for use of preconditioning (default is none), -\item {} +\item {} \code{numiters} - number of iterations from the most-recent solve, -\item {} +\item {} \code{resnorm} - final linear residual norm from the most-recent solve, -\item {} +\item {} \code{last\_flag} - last error return flag from an internal function, -\item {} +\item {} \code{ATimes} - function pointer to perform \(Av\) product, -\item {} +\item {} \code{ATData} - pointer to structure for \code{ATimes}, -\item {} +\item {} \code{Psetup} - function pointer to preconditioner setup routine, -\item {} +\item {} \code{Psolve} - function pointer to preconditioner solve routine, -\item {} +\item {} \code{PData} - pointer to structure for \code{Psetup} and \code{Psolve}, -\item {} +\item {} \code{s} - vector pointer for supplied scaling matrix (default is \code{NULL}), -\item {} +\item {} \code{r} - a \code{N\_Vector} which holds the preconditioned linear system residual, -\item {} +\item {} \code{p, z, Ap} - \code{N\_Vector} used for workspace by the PCG algorithm. @@ -39006,32 +39056,32 @@ \subsection{SUNLinSol\_PCG Description} This solver is constructed to perform the following operations: \begin{itemize} -\item {} +\item {} During construction all \code{N\_Vector} solver data is allocated, with vectors cloned from a template \code{N\_Vector} that is input, and default solver parameters are set. -\item {} +\item {} User-facing ``set'' routines may be called to modify default solver parameters. -\item {} +\item {} Additional ``set'' routines are called by the SUNDIALS solver that interfaces with SUNLinSol\_PCG to supply the \code{ATimes}, \code{PSetup}, and \code{Psolve} function pointers and \code{s} scaling vector. -\item {} +\item {} In the ``initialize'' call, the solver parameters are checked for validity. -\item {} +\item {} In the ``setup'' call, any non-\code{NULL} \code{PSetup} function is called. Typically, this is provided by the SUNDIALS solver itself, that translates between the generic \code{PSetup} function and the solver-specific routine (solver-supplied or user-supplied). -\item {} +\item {} In the ``solve'' call the PCG iteration is performed. This will include scaling and preconditioning if those options have been supplied. @@ -39042,45 +39092,45 @@ \subsection{SUNLinSol\_PCG Description} ``iterative'' linear solver operations listed in the section {\hyperref[sunlinsol/SUNLinSol_API:sunlinsol-api]{\emph{\DUspan{}{The SUNLinearSolver API}}}}: \begin{itemize} -\item {} +\item {} \code{SUNLinSolGetType\_PCG} -\item {} +\item {} \code{SUNLinSolInitialize\_PCG} -\item {} +\item {} \code{SUNLinSolSetATimes\_PCG} -\item {} +\item {} \code{SUNLinSolSetPreconditioner\_PCG} -\item {} +\item {} \code{SUNLinSolSetScalingVectors\_PCG} -- since PCG only supports symmetric scaling, the second \code{N\_Vector} argument to this function is ignored -\item {} +\item {} \code{SUNLinSolSetup\_PCG} -\item {} +\item {} \code{SUNLinSolSolve\_PCG} -\item {} +\item {} \code{SUNLinSolNumIters\_PCG} -\item {} +\item {} \code{SUNLinSolResNorm\_PCG} -\item {} +\item {} \code{SUNLinSolResid\_PCG} -\item {} +\item {} \code{SUNLinSolLastFlag\_PCG} -\item {} +\item {} \code{SUNLinSolSpace\_PCG} -\item {} +\item {} \code{SUNLinSolFree\_PCG} \end{itemize} @@ -39097,19 +39147,19 @@ \section{SUNLinearSolver Examples} The following is a list of the example functions in \code{test\_sunlinsol.c}: \begin{itemize} -\item {} +\item {} \code{Test\_SUNLinSolGetType}: Verifies the returned solver type against the value that should be returned. -\item {} +\item {} \code{Test\_SUNLinSolInitialize}: Verifies that \code{SUNLinSolInitialize} can be called and returns successfully. -\item {} +\item {} \code{Test\_SUNLinSolSetup}: Verifies that \code{SUNLinSolSetup} can be called and returns successfully. -\item {} +\item {} \code{Test\_SUNLinSolSolve}: Given a \code{SUNMatrix} object \(A\), \code{N\_Vector} objects \(x\) and \(b\) (where \(Ax=b\)) and a desired solution tolerance \code{tol}, this routine clones @@ -39120,39 +39170,39 @@ \section{SUNLinearSolver Examples} prior to returning (in case the calling routine would like to investigate further). -\item {} +\item {} \code{Test\_SUNLinSolSetATimes} (iterative solvers only): Verifies that \code{SUNLinSolSetATimes} can be called and returns successfully. -\item {} +\item {} \code{Test\_SUNLinSolSetPreconditioner} (iterative solvers only): Verifies that \code{SUNLinSolSetPreconditioner} can be called and returns successfully. -\item {} +\item {} \code{Test\_SUNLinSolSetScalingVectors} (iterative solvers only): Verifies that \code{SUNLinSolSetScalingVectors} can be called and returns successfully. -\item {} +\item {} \code{Test\_SUNLinSolLastFlag}: Verifies that \code{SUNLinSolLastFlag} can be called, and outputs the result to \code{stdout}. -\item {} +\item {} \code{Test\_SUNLinSolNumIters} (iterative solvers only): Verifies that \code{SUNLinSolNumIters} can be called, and outputs the result to \code{stdout}. -\item {} +\item {} \code{Test\_SUNLinSolResNorm} (iterative solvers only): Verifies that \code{SUNLinSolResNorm} can be called, and that the result is non-negative. -\item {} +\item {} \code{Test\_SUNLinSolResid} (iterative solvers only): Verifies that \code{SUNLinSolResid} can be called. -\item {} +\item {} \code{Test\_SUNLinSolSpace} verifies that \code{SUNLinSolSpace} can be called, and outputs the results to \code{stdout}. @@ -39236,7 +39286,7 @@ \subsection{SUNNonlinearSolver core functions} nonlinear solver type. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object \end{itemize} @@ -39246,11 +39296,11 @@ \subsection{SUNNonlinearSolver core functions} \textbf{Return value:} the SUNNonlinSol type identifier (of type \code{int}) will be one of the following: \begin{itemize} -\item {} +\item {} \code{SUNNONLINEARSOLVER\_ROOTFIND} -- \code{0}, the SUNNonlinSol module solves \(F(y) = 0\). -\item {} +\item {} \code{SUNNONLINEARSOLVER\_FIXEDPOINT} -- \code{1}, the SUNNonlinSol module solves \(G(y) = y\). @@ -39267,7 +39317,7 @@ \subsection{SUNNonlinearSolver core functions} allocations. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object \end{itemize} @@ -39292,13 +39342,13 @@ \subsection{SUNNonlinearSolver core functions} solver setup needed for a nonlinear solve. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{y} -- the initial iteration passed to the nonlinear solver. -\item {} +\item {} \emph{mem} -- the SUNDIALS integrator memory structure. \end{itemize} @@ -39322,32 +39372,32 @@ \subsection{SUNNonlinearSolver core functions} nonlinear system \(F(y)=0\) or \(G(y)=y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{y0} -- the predicted value for the new solution state. This \emph{must} remain unchanged throughout the solution process. See the {\hyperref[sunnonlinsol/ARKode_Interface:sunnonlinsol-arkode]{\emph{\DUspan{}{ARKode SUNNonlinearSolver interface}}}} section for more detail on the nonlinear system formulation. -\item {} +\item {} \emph{ycor} -- on input the initial guess for the correction to the predicted state (zero) and on output the final correction to the predicted state. See the {\hyperref[sunnonlinsol/ARKode_Interface:sunnonlinsol-arkode]{\emph{\DUspan{}{ARKode SUNNonlinearSolver interface}}}} section for more detail on the nonlinear system formulation. -\item {} +\item {} \emph{w} -- the solution error weight vector used for computing weighted error norms. -\item {} +\item {} \emph{tol} -- the requested solution tolerance in the weighted root-mean-squared norm. -\item {} +\item {} \emph{callLSetup} -- a flag indicating that the integrator recommends for the linear solver setup function to be called. -\item {} +\item {} \emph{mem} -- the SUNDIALS integrator memory structure. \end{itemize} @@ -39370,7 +39420,7 @@ \subsection{SUNNonlinearSolver core functions} memory allocated by the nonlinear solver. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object \end{itemize} @@ -39403,10 +39453,10 @@ \subsection{SUNNonlinearSolver set functions} \(G(y)\) in \(G(y)=y\) for \code{SUNNONLINEARSOLVER\_FIXEDPOINT} modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{SysFn} -- the function defining the nonlinear system. See the section {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-sunsuppliedfn]{\emph{\DUspan{}{Functions provided by SUNDIALS integrators}}}} for the definition of \code{SUNNonlinSolSysFn()}. @@ -39429,10 +39479,10 @@ \subsection{SUNNonlinearSolver set functions} to its linear solver setup function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{SetupFn} -- a wrapper function to the SUNDIALS integrator's linear solver setup function. See the section {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-sunsuppliedfn]{\emph{\DUspan{}{Functions provided by SUNDIALS integrators}}}} for the definition of \code{SUNNonlinLSetupFn()}. @@ -39465,10 +39515,10 @@ \subsection{SUNNonlinearSolver set functions} access to its linear solver solve function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{SolveFn} -- a wrapper function to the SUNDIALS integrator's linear solver solve function. See the section {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-sunsuppliedfn]{\emph{\DUspan{}{Functions provided by SUNDIALS integrators}}}} for the definition of @@ -39501,16 +39551,16 @@ \subsection{SUNNonlinearSolver set functions} nonlinear convergence criteria, but may be replaced by the user. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{CTestFn} -- a SUNDIALS integrator's nonlinear solver convergence test function. See the section {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-sunsuppliedfn]{\emph{\DUspan{}{Functions provided by SUNDIALS integrators}}}} for the definition of \code{SUNNonlinSolConvTestFn()}. -\item {} +\item {} \emph{ctest\_data} -- is a data pointer passed to \emph{CTestFn} every time it is called. @@ -39536,10 +39586,10 @@ \subsection{SUNNonlinearSolver set functions} iteration limit, but may be adjusted by the user. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{maxiters} -- the maximum number of nonlinear iterations. \end{itemize} @@ -39573,10 +39623,10 @@ \subsection{SUNNonlinearSolver get functions} statistics, but may also be called by the user. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{niters} -- the total number of nonlinear solver iterations. \end{itemize} @@ -39600,10 +39650,10 @@ \subsection{SUNNonlinearSolver get functions} is \emph{optional}. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{iter} -- the nonlinear solver iteration in the current solve starting from zero. @@ -39624,10 +39674,10 @@ \subsection{SUNNonlinearSolver get functions} statistics, but may also be called by the user. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{nconvfails} -- the total number of nonlinear solver convergence failures. \end{itemize} @@ -39666,16 +39716,16 @@ \subsection{Functions provided by SUNDIALS integrators} vector \emph{ycor} will be left unchanged. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ycor} -- is the current correction to the predicted state at which the nonlinear system should be evaluated. See the {\hyperref[sunnonlinsol/ARKode_Interface:sunnonlinsol-arkode]{\emph{\DUspan{}{ARKode SUNNonlinearSolver interface}}}} section for more detail on the nonlinear system function. -\item {} +\item {} \emph{F} -- is the output vector containing \(F(y)\) or \(G(y)\), depending on the solver type. -\item {} +\item {} \emph{mem} -- is the SUNDIALS integrator memory structure. \end{itemize} @@ -39705,15 +39755,15 @@ \subsection{Functions provided by SUNDIALS integrators} for setting up linear solves with SUNLinSol modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{jbad} -- is an input indicating whether the nonlinear solver believes that \(A\) has gone stale (\code{SUNTRUE}) or not (\code{SUNFALSE}). -\item {} +\item {} \emph{jcur} -- is an output indicating whether the routine has updated the Jacobian \(A\) (\code{SUNTRUE}) or not (\code{SUNFALSE}). -\item {} +\item {} \emph{mem} -- is the SUNDIALS integrator memory structure. \end{itemize} @@ -39750,11 +39800,11 @@ \subsection{Functions provided by SUNDIALS integrators} for solving linear systems with SUNLinSol modules. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{b} -- contains the right-hand side vector for the linear solve on input and the solution to the linear system on output. -\item {} +\item {} \emph{mem} -- is the SUNDIALS integrator memory structure. \end{itemize} @@ -39789,22 +39839,22 @@ \subsection{Functions provided by SUNDIALS integrators} but users may supply custom problem-specific versions as desired. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- is the SUNNonlinSol object. -\item {} +\item {} \emph{ycor} -- is the current correction (nonlinear iterate). -\item {} +\item {} \emph{del} -- is the difference between the current and prior nonlinear iterates. -\item {} +\item {} \emph{tol} -- is the nonlinear solver tolerance. -\item {} +\item {} \emph{ewt} -- is the weight vector used in computing weighted norms. -\item {} +\item {} \emph{ctest\_data} -- is the data pointer provided to {\hyperref[sunnonlinsol/SUNNonlinSol_API:c.SUNNonlinSolSetConvTestFn]{\emph{\code{SUNNonlinSolSetConvTestFn()}}}}. @@ -39816,14 +39866,14 @@ \subsection{Functions provided by SUNDIALS integrators} negative value if an unrecoverable error occurred or one of the following: \begin{itemize} -\item {} +\item {} \code{SUN\_NLS\_SUCCESS} -- the iteration is converged. -\item {} +\item {} \code{SUN\_NLS\_CONTINUE} -- the iteration has not converged, keep iterating. -\item {} +\item {} \code{SUN\_NLS\_CONV\_RECVR} -- the iteration appears to be diverging, try to recover. @@ -39853,65 +39903,65 @@ \subsection{SUNNonlinearSolver return codes} \hline Name - & + & Value - & + & Description \\ \hline SUN\_NLS\_SUCCESS - & + & 0 - & + & successful call or converged solve \\ \hline SUN\_NLS\_CONTINUE - & + & 901 - & + & the nonlinear solver is not converged, keep iterating \\ \hline SUN\_NLS\_CONV\_RECVR - & + & 902 - & + & the nonlinear solver appears to be diverging, try to recover \\ \hline SUN\_NLS\_MEM\_NULL - & + & -901 - & + & a memory argument is \code{NULL} \\ \hline SUN\_NLS\_MEM\_FAIL - & + & -902 - & + & a memory access or allocation failed \\ \hline SUN\_NLS\_ILL\_INPUT - & + & -903 - & + & an illegal input option was provided \\ \hline SUN\_NLS\_VECTOROP\_ERR - & + & -904 - & + & a NVECTOR operation failed \\ \hline SUN\_NLS\_EXT\_FAIL - & + & -905 - & + & an external library call returned an error \\ \hline\end{tabulary} @@ -39987,10 +40037,10 @@ \subsection{Implementing a Custom SUNNonlinearSolver Module} \label{sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-custom}\label{sunnonlinsol/SUNNonlinSol_API:implementing-a-custom-sunnonlinearsolver-module} A SUNNonlinSol implementation \emph{must} do the following: \begin{itemize} -\item {} +\item {} Specify the content of the SUNNonlinSol module. -\item {} +\item {} Define and implement the required nonlinear solver operations defined in Sections {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-corefn]{\emph{\DUspan{}{SUNNonlinearSolver core functions}}}} through {\hyperref[sunnonlinsol/SUNNonlinSol_API:sunnonlinsol-getfn]{\emph{\DUspan{}{SUNNonlinearSolver get functions}}}}. Note that the names of the module @@ -39999,7 +40049,7 @@ \subsection{Implementing a Custom SUNNonlinearSolver Module} \code{SUNNonlinearSolver} internal data representations) in the same code. -\item {} +\item {} Define and implement a user-callable constructor to create a \code{SUNNonlinearSolver} object. @@ -40036,7 +40086,7 @@ \subsection{Implementing a Custom SUNNonlinearSolver Module} \begin{quote} \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinearSolver object \end{itemize} @@ -40050,13 +40100,13 @@ \subsection{Implementing a Custom SUNNonlinearSolver Module} Additionally, a \code{SUNNonlinearSolver} implementation \emph{may} do the following: \begin{itemize} -\item {} +\item {} Define and implement additional user-callable ``set'' routines acting on the \code{SUNNonlinearSolver} object, e.g., for setting various configuration options to tune the performance of the nonlinear solve algorithm. -\item {} +\item {} Provide additional user-callable ``get'' routines acting on the \code{SUNNonlinearSolver} object, e.g., for returning various solve statistics. @@ -40112,19 +40162,19 @@ \subsection{ARKStep advanced output functions} Returns the current state vector \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{y} -- N\_Vector pointer that will get set to the current state vector \end{itemize} \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -40140,10 +40190,10 @@ \subsection{ARKStep advanced output functions} Returns the current value of the scalar \(\gamma\) \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{arkode\_mem} -- pointer to the ARKStep memory block. -\item {} +\item {} \emph{gamma} -- the current value of the scalar \(\gamma\) appearing in the \end{itemize} @@ -40151,10 +40201,10 @@ \subsection{ARKStep advanced output functions} Newton equation \(A = I - \gamma J\) or \(A = M - \gamma J\). \item[{\textbf{Return value:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{ARK\_SUCCESS} if successful -\item {} +\item {} \emph{ARK\_MEM\_NULL} if the ARKStep memory was \code{NULL} \end{itemize} @@ -40209,11 +40259,11 @@ \subsection{SUNNonlinearSolver\_Newton description} solvers). Specifically, SUNNonlinSol\_Newton will call the \code{SUNNonlinSolLSetupFn()} function in two instances: \begin{enumerate} -\item {} +\item {} when requested by the integrator (the input \code{callLSetSetup} is \code{SUNTRUE}) before attempting the Newton iteration, or -\item {} +\item {} when reattempting the nonlinear solve after a recoverable failure occurs in the Newton iteration with stale Jacobian information (\code{jcur} is \code{SUNFALSE}). In this case, SUNNonlinSol\_Newton @@ -40250,7 +40300,7 @@ \subsection{SUNNonlinearSolver\_Newton functions} method. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- a template for cloning vectors needed within the solver. \end{itemize} @@ -40284,10 +40334,10 @@ \subsection{SUNNonlinearSolver\_Newton functions} residual function that defines the nonlinear system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{SysFn} -- the function defining the nonlinear system. \end{itemize} @@ -40333,40 +40383,40 @@ \subsection{SUNNonlinearSolver\_Newton content} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{Sys} -- the function for evaluating the nonlinear system, -\item {} +\item {} \code{LSetup} -- the package-supplied function for setting up the linear solver, -\item {} +\item {} \code{LSolve} -- the package-supplied function for performing a linear solve, -\item {} +\item {} \code{CTest} -- the function for checking convergence of the Newton iteration, -\item {} +\item {} \code{delta} -- the Newton iteration update vector, -\item {} +\item {} \code{jcur} -- the Jacobian status (\code{SUNTRUE} = current, \code{SUNFALSE} = stale), -\item {} +\item {} \code{curiter} -- the current number of iterations in the solve attempt, -\item {} +\item {} \code{maxiters} -- the maximum number of Newton iterations allowed in a solve, -\item {} +\item {} \code{niters} -- the total number of nonlinear iterations across all solves, -\item {} +\item {} \code{nconvfails} -- the total number of nonlinear convergence failures across all solves, -\item {} +\item {} \code{ctest\_data} -- the data pointer passed to the convergence test function. \end{itemize} @@ -40390,11 +40440,11 @@ \subsection{SUNNonlinearSolver\_Newton Fortran interface} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, ARKode=4. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). See printed message for details in case of failure. @@ -40495,10 +40545,10 @@ \subsection{SUNNonlinearSolver\_FixedPoint functions} solve nonlinear systems of the form \(G(y) = y\). \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{y} -- a template for cloning vectors needed within the solver. -\item {} +\item {} \emph{m} -- the number of acceleration vectors to use. \end{itemize} @@ -40536,10 +40586,10 @@ \subsection{SUNNonlinearSolver\_FixedPoint functions} the fixed-point function that defines the nonlinear system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a SUNNonlinSol object -\item {} +\item {} \emph{SysFn} -- the function defining the nonlinear system. \end{itemize} @@ -40595,39 +40645,39 @@ \subsection{SUNNonlinearSolver\_FixedPoint content} The following entries of the \emph{content} field are always allocated: \begin{itemize} -\item {} +\item {} \code{Sys} -- function for evaluating the nonlinear system, -\item {} +\item {} \code{CTest} -- function for checking convergence of the fixed point iteration, -\item {} +\item {} \code{yprev} -- \code{N\_Vector} used to store previous fixed-point iterate, -\item {} +\item {} \code{gy} -- \code{N\_Vector} used to store \(G(y)\) in fixed-point algorithm, -\item {} +\item {} \code{delta} -- \code{N\_Vector} used to store difference between successive fixed-point iterates, -\item {} +\item {} \code{curiter} -- the current number of iterations in the solve attempt, -\item {} +\item {} \code{maxiters} -- the maximum number of fixed-point iterations allowed in a solve, -\item {} +\item {} \code{niters} -- the total number of nonlinear iterations across all solves, -\item {} +\item {} \code{nconvfails} -- the total number of nonlinear convergence failures across all solves, -\item {} +\item {} \code{ctest\_data} -- the data pointer passed to the convergence test function, and -\item {} +\item {} \code{m} -- number of acceleration vectors. \end{itemize} @@ -40636,34 +40686,34 @@ \subsection{SUNNonlinearSolver\_FixedPoint content} to {\hyperref[sunnonlinsol/SUNNonlinSol_FixedPoint:c.SUNNonlinSol_FixedPoint]{\emph{\code{SUNNonlinSol\_FixedPoint()}}}}), then the following items are also allocated within the \emph{content} field: \begin{itemize} -\item {} +\item {} \code{imap} -- index array used in acceleration algorithm (length \code{m}), -\item {} +\item {} \code{R} -- small matrix used in acceleration algorithm (length \code{m*m}), -\item {} +\item {} \code{gamma} -- small vector used in acceleration algorithm (length \code{m}), -\item {} +\item {} \code{cvals} -- small vector used in acceleration algorithm (length \code{m+1}), -\item {} +\item {} \code{df} -- array of \code{N\_Vectors} used in acceleration algorithm (length \code{m}), -\item {} +\item {} \code{dg} -- array of \code{N\_Vectors} used in acceleration algorithm (length \code{m}), -\item {} +\item {} \code{q} -- array of \code{N\_Vectors} used in acceleration algorithm (length \code{m}), -\item {} +\item {} \code{Xvecs} -- \code{N\_Vector} pointer array used in acceleration algorithm (length \code{m+1}), -\item {} +\item {} \code{fold} -- \code{N\_Vector} used in acceleration algorithm, and -\item {} +\item {} \code{gold} -- \code{N\_Vector} used in acceleration algorithm. \end{itemize} @@ -40687,14 +40737,14 @@ \subsection{SUNNonlinearSolver\_FixedPoint Fortran interface} been initialized. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{CODE} (\code{int}, input) -- flag denoting the SUNDIALS solver this matrix will be used for: CVODE=1, IDA=2, ARKode=4. -\item {} +\item {} \emph{M} (\code{int}, input) -- the number of acceleration vectors. -\item {} +\item {} \emph{IER} (\code{int}, output) -- return flag (0 success, -1 for failure). See printed message for details in case of failure. @@ -40735,7 +40785,7 @@ \subsection{SUNNonlinearSolver\_PetscSNES description} \emph{Important usage notes for the {}`{}`SUNNonlinearSolver\_PetscSNES{}`{}` implementation are provided below:} \begin{itemize} -\item {} +\item {} The \code{SUNNonlinearSolver\_PetscSNES} implementation handles calling \code{SNESSetFunction} at construction. The actual residual function \(F(y)\) is set by the SUNDIALS integrator when the \code{SUNNonlinearSolver\_PetscSNES} @@ -40745,20 +40795,20 @@ \subsection{SUNNonlinearSolver\_PetscSNES description} user calls \code{SUNNonlinSol\_PetscSNES} with the new \code{SNES} object immediately after calling \code{SNESCreate}. -\item {} +\item {} The number of nonlinear iterations is tracked by SUNDIALS separately from the count kept by SNES. As such, the function \code{SUNNonlinSolGetNumIters} reports the cumulative number of iterations across the lifetime of the \code{SUNNonlinearSolver} object. -\item {} +\item {} Some ``converged'' and ``diverged'' convergence reasons returned by SNES are treated as recoverable convergence failures by SUNDIALS. Therefore, the count of convergence failures returned by \code{SUNNonlinSolGetNumConvFails} will reflect the number of recoverable convergence failures as determined by SUNDIALS, and may differ from the count returned by \code{SNESGetNonlinearStepFailures}. -\item {} +\item {} The \code{SUNNonlinearSolver\_PetscSNES} module is not currently compatible with the CVODES or IDAS staggered or simultaneous sensitivity strategies. @@ -40778,10 +40828,10 @@ \subsection{SUNNonlinearSolver\_PetscSNES functions} will call \code{SNESSetFunction} on the provided \code{SNES} object. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{snes} -- a PETSc \code{SNES} object -\item {} +\item {} \emph{y} -- a \code{N\_Vector} object of type NVECTOR\_PETSC that is used as a template for the residual vector @@ -40821,10 +40871,10 @@ \subsection{SUNNonlinearSolver\_PetscSNES functions} was wrapped. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a \code{SUNNonlinearSolver} object -\item {} +\item {} \emph{snes} -- a pointer to a PETSc \code{SNES} object that will be set upon return \end{itemize} @@ -40844,10 +40894,10 @@ \subsection{SUNNonlinearSolver\_PetscSNES functions} returned by the last internal call to a PETSc API function. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a \code{SUNNonlinearSolver} object -\item {} +\item {} \emph{error} -- a pointer to a PETSc error integer that will be set upon return \end{itemize} @@ -40867,10 +40917,10 @@ \subsection{SUNNonlinearSolver\_PetscSNES functions} function that defines the nonlinear system. \begin{description} \item[{\textbf{Arguments:}}] \leavevmode\begin{itemize} -\item {} +\item {} \emph{NLS} -- a \code{SUNNonlinearSolver} object -\item {} +\item {} \emph{SysFn} -- the function defining the nonlinear system \end{itemize} @@ -40905,34 +40955,34 @@ \subsection{SUNNonlinearSolver\_PetscSNES content} These entries of the \emph{content} field contain the following information: \begin{itemize} -\item {} +\item {} \code{sysfn\_last\_err} -- last error returned by the system defining function, -\item {} +\item {} \code{petsc\_last\_err} -- last error returned by PETSc -\item {} +\item {} \code{nconvfails} -- number of nonlinear converge failures (recoverable or not), -\item {} +\item {} \code{nni} -- number of nonlinear iterations, -\item {} +\item {} \code{imem} -- SUNDIALS integrator memory, -\item {} +\item {} \code{snes} -- PETSc \code{SNES} object, -\item {} +\item {} \code{r} -- the nonlinear residual, -\item {} +\item {} \code{y} -- wrapper for PETSc vectors used in the system function, -\item {} +\item {} \code{f} -- wrapper for PETSc vectors used in the system function, -\item {} +\item {} \code{Sys} -- nonlinear system definining function. \end{itemize} @@ -40964,7 +41014,7 @@ \chapter{ARKode Installation Procedure} method of installation. The explanations of the installation procedure begins with a few common observations: \begin{itemize} -\item {} +\item {} The remainder of this chapter will follow these conventions: \begin{description} \item[{\code{SOLVERDIR}}] \leavevmode @@ -40983,18 +41033,18 @@ \chapter{ARKode Installation Procedure} \end{description} -\item {} +\item {} For SUNDIALS' CMake-based installation, in-source builds are prohibited; in other words, the build directory \code{BUILDDIR} can \textbf{not} be the same as \code{SOLVERDIR} and such an attempt will lead to an error. This prevents ``polluting'' the source tree and allows efficient builds for different configurations and/or options. -\item {} +\item {} The installation directory \code{INSTDIR} can not be the same as the source directory \code{SOLVERDIR}. -\item {} +\item {} By default, only the libraries and header files are exported to the installation directory \code{INSTDIR}. If enabled by the user (with the appropriate toggle for CMake), the @@ -41012,7 +41062,7 @@ \chapter{ARKode Installation Procedure} to install them. (This can be used as a sanity check for the freshly built libraries.) -\item {} +\item {} Even if generation of shared libraries is enabled, only static libraries are created for the FCMIX modules. Because of the use of fixed names for the Fortran user-provided subroutines, FCMIX shared @@ -41025,10 +41075,10 @@ \chapter{ARKode Installation Procedure} installed libraries and exported header files, are provided in the following subsections: \begin{itemize} -\item {} +\item {} {\hyperref[Install:installation-cmake]{\emph{\DUspan{}{CMake-based installation}}}} -\item {} +\item {} {\hyperref[Install:installation-results]{\emph{\DUspan{}{Installed libraries and exported header files}}}} \end{itemize} @@ -41097,37 +41147,37 @@ \subsubsection{Building with the GUI} \label{Install:building-with-the-gui}\label{Install:index-2} Using CMake with the \code{ccmake} GUI follows the general process: \begin{itemize} -\item {} +\item {} Select and modify values, run configure (\code{c} key) -\item {} +\item {} New values are denoted with an asterisk -\item {} +\item {} To set a variable, move the cursor to the variable and press enter \begin{itemize} -\item {} +\item {} If it is a boolean (ON/OFF) it will toggle the value -\item {} +\item {} If it is string or file, it will allow editing of the string -\item {} +\item {} For file and directories, the \code{\textless{}tab\textgreater{}} key can be used to complete \end{itemize} -\item {} +\item {} Repeat until all values are set as desired and the generate option is available (\code{g} key) -\item {} +\item {} Some variables (advanced variables) are not visible right away -\item {} +\item {} To see advanced variables, toggle to advanced mode (\code{t} key) -\item {} +\item {} To search for a variable press \code{/} key, and to repeat the search, press the \code{n} key @@ -41135,43 +41185,43 @@ \subsubsection{Building with the GUI} Using CMake with the \code{cmake-gui} GUI follows a similar process: \begin{itemize} -\item {} +\item {} Select and modify values, click \code{Configure} -\item {} +\item {} The first time you click \code{Configure}, make sure to pick the appropriate generator (the following will ssume generation of Unix Makfiles). -\item {} +\item {} New values are highlighted in red -\item {} +\item {} To set a variable, click on or move the cursor to the variable and press enter \begin{itemize} -\item {} +\item {} If it is a boolean (\code{ON/OFF}) it will check/uncheck the box -\item {} +\item {} If it is string or file, it will allow editing of the string. Additionally, an ellipsis button will appear \code{...} on the far right of the entry. Clicking this button will bring up the file or directory selection dialog. -\item {} +\item {} For files and directories, the \code{\textless{}tab\textgreater{}} key can be used to complete \end{itemize} -\item {} +\item {} Repeat until all values are set as desired and click the \code{Generate} button -\item {} +\item {} Some variables (advanced variables) are not visible right away -\item {} +\item {} To see advanced variables, click the \code{advanced} button \end{itemize} @@ -42199,43 +42249,43 @@ \subsection{Configuring, building, and installing on Windows} CMake can also be used to build SUNDIALS on Windows. To build SUNDIALS for use with Visual Studio the following steps should be performed: \begin{enumerate} -\item {} +\item {} Unzip the downloaded tar file(s) into a directory. This will be the \code{SOLVERDIR} -\item {} +\item {} Create a separate \code{BUILDDIR} -\item {} +\item {} Open a Visual Studio Command Prompt and cd to \code{BUILDDIR} -\item {} +\item {} Run \code{cmake-gui ../SOLVERDIR} \begin{enumerate} -\item {} +\item {} Hit Configure -\item {} +\item {} Check/Uncheck solvers to be built -\item {} +\item {} Change \code{CMAKE\_INSTALL\_PREFIX} to \code{INSTDIR} -\item {} +\item {} Set other options as desired -\item {} +\item {} Hit Generate \end{enumerate} -\item {} +\item {} Back in the VS Command Window: \begin{enumerate} -\item {} +\item {} Run \code{msbuild ALL\_BUILD.vcxproj} -\item {} +\item {} Run \code{msbuild INSTALL.vcxproj} \end{enumerate} @@ -42302,9 +42352,9 @@ \subsection{Table: SUNDIALS libraries and header files} Shared - & + & Header files - & + & \code{sundials/sundials\_band.h}, \code{sundials/sundials\_config.h}, \code{sundials/sundials\_dense.h}, @@ -42322,457 +42372,457 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline NVECTOR\_SERIAL - & + & Libraries - & + & \code{libsundials\_nvecserial.LIB}, \code{libsundials\_fnvecserial.a} \\ \hline NVECTOR\_SERIAL - & + & Header files - & + & \code{nvector/nvector\_serial.h} \\ \hline NVECTOR\_PARALLEL - & + & Libraries - & + & \code{libsundials\_nvecparallel.LIB}, \code{libsundials\_fnvecparallel.a} \\ \hline NVECTOR\_PARALLEL - & + & Header files - & + & \code{nvector/nvector\_parallel.h} \\ \hline NVECTOR\_OPENMP - & + & Libraries - & + & \code{libsundials\_nvecopenmp.LIB}, \code{libsundials\_fnvecopenmp.a} \\ \hline NVECTOR\_OPENMP - & + & Header files - & + & \code{nvector/nvector\_openmp.h} \\ \hline NVECTOR\_PTHREADS - & + & Libraries - & + & \code{libsundials\_nvecpthreads.LIB}, \code{libsundials\_fnvecpthreads.a} \\ \hline NVECTOR\_PTHREADS - & + & Header files - & + & \code{nvector/nvector\_pthreads.h} \\ \hline NVECTOR\_PARHYP - & + & Libraries - & + & \code{libsundials\_nvecparhyp.LIB} \\ \hline NVECTOR\_PARHYP - & + & Header files - & + & \code{nvector/nvector\_parhyp.h} \\ \hline NVECTOR\_PETSC - & + & Libraries - & + & \code{libsundials\_nvecpetsc.LIB} \\ \hline NVECTOR\_PETSC - & + & Header files - & + & \code{nvector/nvector\_petsc.h} \\ \hline NVECTOR\_CUDA - & + & Libraries - & + & \code{libsundials\_nveccuda.LIB} \\ \hline NVECTOR\_CUDA - & + & Header files - & + & \code{nvector/nvector\_cuda.h} \\ \hline NVECTOR\_RAJA - & + & Libraries - & + & \code{libsundials\_nvecraja.LIB} \\ \hline NVECTOR\_RAJA - & + & Header files - & + & \code{nvector/nvector\_raja.h} \\ \hline NVECTOR\_MANYVECTOR - & + & Libraries - & + & \code{libsundials\_nvecmanyvector.LIB} \\ \hline NVECTOR\_MANYVECTOR - & + & Header files - & + & \code{nvector/nvector\_manyvector.h} \\ \hline NVECTOR\_MPIMANYVECTOR - & + & Libraries - & + & \code{libsundials\_nvecmpimanyvector.LIB} \\ \hline NVECTOR\_MPIMANYVECTOR - & + & Header files - & + & \code{nvector/nvector\_mpimanyvector.h} \\ \hline NVECTOR\_MPIPLUSX - & + & Libraries - & + & \code{libsundials\_nvecmpiplusx.LIB} \\ \hline NVECTOR\_MPIPLUSX - & + & Header files - & + & \code{nvector/nvector\_mpiplusx.h} \\ \hline SUNMATRIX\_BAND - & + & Libraries - & + & \code{libsundials\_sunmatrixband.LIB}, \code{libsundials\_fsunmatrixband.a} \\ \hline SUNMATRIX\_BAND - & + & Header files - & + & \code{sunmatrix/sunmatrix\_band.h} \\ \hline SUNMATRIX\_DENSE - & + & Libraries - & + & \code{libsundials\_sunmatrixdense.LIB}, \code{libsundials\_fsunmatrixdense.a} \\ \hline SUNMATRIX\_DENSE - & + & Header files - & + & \code{sunmatrix/sunmatrix\_dense.h} \\ \hline SUNMATRIX\_SPARSE - & + & Libraries - & + & \code{libsundials\_sunmatrixsparse.LIB}, \code{libsundials\_fsunmatrixsparse.a} \\ \hline SUNMATRIX\_SPARSE - & + & Header files - & + & \code{sunmatrix/sunmatrix\_sparse.h} \\ \hline SUNLINSOL\_BAND - & + & Libraries - & + & \code{libsundials\_sunlinsolband.LIB}, \code{libsundials\_fsunlinsolband.a} \\ \hline SUNLINSOL\_BAND - & + & Header files - & + & \code{sunlinsol/sunlinsol\_band.h} \\ \hline SUNLINSOL\_DENSE - & + & Libraries - & + & \code{libsundials\_sunlinsoldense.LIB}, \code{libsundials\_fsunlinsoldense.a} \\ \hline SUNLINSOL\_DENSE - & + & Header files - & + & \code{sunlinsol/sunlinsol\_dense.h} \\ \hline SUNLINSOL\_KLU - & + & Libraries - & + & \code{libsundials\_sunlinsolklu.LIB}, \code{libsundials\_fsunlinsolklu.a} \\ \hline SUNLINSOL\_KLU - & + & Header files - & + & \code{sunlinsol/sunlinsol\_klu.h} \\ \hline SUNLINSOL\_LAPACKBAND - & + & Libraries - & + & \code{libsundials\_sunlinsollapackband.LIB}, \code{libsundials\_fsunlinsollapackband.a} \\ \hline SUNLINSOL\_LAPACKBAND - & + & Header files - & + & \code{sunlinsol/sunlinsol\_lapackband.h} \\ \hline SUNLINSOL\_LAPACKDENSE - & + & Libraries - & + & \code{libsundials\_sunlinsollapackdense.LIB}, \code{libsundials\_fsunlinsollapackdense.a} \\ \hline SUNLINSOL\_LAPACKDENSE - & + & Header files - & + & \code{sunlinsol/sunlinsol\_lapackdense.h} \\ \hline SUNLINSOL\_PCG - & + & Libraries - & + & \code{libsundials\_sunlinsolpcg.LIB}, \code{libsundials\_fsunlinsolpcg.a} \\ \hline SUNLINSOL\_PCG - & + & Header files - & + & \code{sunlinsol/sunlinsol\_pcg.h} \\ \hline SUNLINSOL\_SPBCGS - & + & Libraries - & + & \code{libsundials\_sunlinsolspbcgs.LIB}, \code{libsundials\_fsunlinsolspbcgs.a} \\ \hline SUNLINSOL\_SPBCGS - & + & Header files - & + & \code{sunlinsol/sunlinsol\_spbcgs.h} \\ \hline SUNLINSOL\_SPFGMR - & + & Libraries - & + & \code{libsundials\_sunlinsolspfgmr.LIB}, \code{libsundials\_fsunlinsolspfgmr.a} \\ \hline SUNLINSOL\_SPFGMR - & + & Header files - & + & \code{sunlinsol/sunlinsol\_spfgmr.h} \\ \hline SUNLINSOL\_SPGMR - & + & Libraries - & + & \code{libsundials\_sunlinsolspgmr.LIB}, \code{libsundials\_fsunlinsolspgmr.a} \\ \hline SUNLINSOL\_SPGMR - & + & Header files - & + & \code{sunlinsol/sunlinsol\_spgmr.h} \\ \hline SUNLINSOL\_SPTFQMR - & + & Libraries - & + & \code{libsundials\_sunlinsolsptfqmr.LIB}, \code{libsundials\_fsunlinsolsptfqmr.a} \\ \hline SUNLINSOL\_SPTFQMR - & + & Header files - & + & \code{sunlinsol/sunlinsol\_sptfqmr.h} \\ \hline SUNLINSOL\_SUPERLUMT - & + & Libraries - & + & \code{libsundials\_sunlinsolsuperlumt.LIB}, \code{libsundials\_fsunlinsolsuperlumt.a} \\ \hline SUNLINSOL\_SUPERLUMT - & + & Header files - & + & \code{sunlinsol/sunlinsol\_superlumt.h} \\ \hline SUNLINSOL\_SUPERLUDIST - & + & Libraries - & + & \code{libsundials\_sunlinsolsuperludist.LIB}, \\ \hline SUNLINSOL\_SUPERLUDIST - & + & Header files - & + & \code{sunlinsol/sunlinsol\_superludist.h} \\ \hline SUNLINSOL\_CUSOLVERSP\_BATCHQR - & + & Libraries - & + & \code{libsundials\_sunlinsolcusolversp.LIB}, \\ \hline SUNLINSOL\_CUSOLVERSP\_BATCHQR - & + & Header files - & + & \code{sunlinsol/sunlinsol\_cusolversp\_batchqr.h} \\ \hline SUNNONLINSOL\_NEWTON - & + & Libraries - & + & \code{libsundials\_sunnonlinsolnewton.LIB}, \code{libsundials\_fsunnonlinsolnewton.a} \\ \hline SUNNONLINSOL\_NEWTON - & + & Header files - & + & \code{sunnonlinsol/sunnonlinsol\_newton.h} \\ \hline SUNNONLINSOL\_FIXEDPOINT - & + & Libraries - & + & \code{libsundials\_sunnonlinsolfixedpoint.LIB}, \code{libsundials\_fsunnonlinsolfixedpoint.a} \\ \hline SUNNONLINSOL\_FIXEDPOINT - & + & Header files - & + & \code{sunnonlinsol/sunnonlinsol\_fixedpoint.h} \\ \hline SUNNONLINSOL\_PETSCSNES - & + & Libraries - & + & \code{libsundials\_sunnonlinsolpetscsnes.LIB}, \\ \hline SUNNONLINSOL\_PETSCSNES - & + & Header files - & + & \code{sunnonlinsol/sunnonlinsol\_petscsnes.h} \\ \hline CVODE - & + & Libraries - & + & \code{libsundials\_cvode.LIB}, \code{libsundials\_fcvode.a} \\ \hline CVODE - & + & Header files - & + & \code{cvode/cvode.h}, \code{cvode/cvode\_bandpre.h}, \code{cvode/cvode\_bbdpre.h}, @@ -42784,16 +42834,16 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline CVODES - & + & Libraries - & + & \code{libsundials\_cvodes.LIB} \\ \hline CVODES - & + & Header files - & + & \code{cvodes/cvodes.h}, \code{cvodes/cvodes\_bandpre.h}, \code{cvodes/cvodes\_bbdpre.h}, @@ -42804,17 +42854,17 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline ARKODE - & + & Libraries - & + & \code{libsundials\_arkode.LIB}, \code{libsundials\_farkode.a} \\ \hline ARKODE - & + & Header files - & + & \code{arkode/arkode.h}, \code{arkode/arkode\_arkstep.h}, \code{arkode/arkode\_bandpre.h}, @@ -42828,17 +42878,17 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline IDA - & + & Libraries - & + & \code{libsundials\_ida.LIB}, \code{libsundials\_fida.a} \\ \hline IDA - & + & Header files - & + & \code{ida/ida.h}, \code{ida/ida\_bbdpre.h}, \code{ida/ida\_direct.h}, @@ -42848,16 +42898,16 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline IDAS - & + & Libraries - & + & \code{libsundials\_idas.LIB} \\ \hline IDAS - & + & Header files - & + & \code{idas/idas.h}, \code{idas/idas\_bbdpre.h} \code{idas/idas\_direct.h}, @@ -42866,17 +42916,17 @@ \subsection{Table: SUNDIALS libraries and header files} \\ \hline KINSOL - & + & Libraries - & + & \code{libsundials\_kinsol.LIB}, \code{libsundials\_fkinsol.a} \\ \hline KINSOL - & + & Header files - & + & \code{kinsol/kinsol.h}, \code{kinsol/kinsol\_bbdpre.h}, \code{kinsol/kinsol\_direct.h}, @@ -43283,16 +43333,16 @@ \chapter{Appendix: Butcher tables} where here \begin{itemize} -\item {} +\item {} \code{NAME} is the author or the name provided by the author (if applicable), -\item {} +\item {} \code{S} is the number of stages in the method, -\item {} +\item {} \code{P} is the global order of accuracy for the embedding, -\item {} +\item {} \code{Q} is the global order of accuracy for the method. \end{itemize} @@ -43327,7 +43377,7 @@ \chapter{Appendix: Butcher tables} may be written as \(e^{i\theta}\) for some value of \(\theta\), we perform the following algorithm to trace out this boundary. \begin{enumerate} -\item {} +\item {} Define an array of values \code{Theta}. Since we wish for a smooth curve, and since we wish to trace out the entire boundary, we choose 10,000 linearly-spaced points from 0 to \(16\pi\). @@ -43338,7 +43388,7 @@ \chapter{Appendix: Butcher tables} converge to the root closest to the previous boundary point, ensuring a smooth plot. -\item {} +\item {} For each value \(\theta \in\) \code{Theta}, we solve the nonlinear equation \begin{gather} @@ -43352,7 +43402,7 @@ \chapter{Appendix: Butcher tables} previous value of \(\theta\), starting with an initial-initial guess of \(\eta=0\) for \(\theta=0\). -\item {} +\item {} We then plot the resulting \(\eta\) values that trace the stability region boundary. @@ -44193,31 +44243,31 @@ \section{Additive Butcher tables} through 5, with embeddings that are of orders 2 through 4. These Butcher table pairs are as follows: \begin{itemize} -\item {} +\item {} \index{ARK-4-2-3 ARK method}3rd-order pair: {\hyperref[Butcher:butcher-ark-4-2-3-e]{\emph{\DUspan{}{ARK-4-2-3 (explicit)}}}} with {\hyperref[Butcher:butcher-ark-4-2-3-i]{\emph{\DUspan{}{ARK-4-2-3 (implicit)}}}}, corresponding to Butcher tables \code{ARK324L2SA\_ERK\_4\_2\_3} and \code{ARK324L2SA\_DIRK\_4\_2\_3} for {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}}. -\item {} +\item {} \index{ARK-6-3-4 ARK method}4th-order pair: {\hyperref[Butcher:butcher-ark-6-3-4-e]{\emph{\DUspan{}{ARK-6-3-4 (explicit)}}}} with {\hyperref[Butcher:butcher-ark-6-3-4-i]{\emph{\DUspan{}{ARK-6-3-4 (implicit)}}}}, corresponding to Butcher tables \code{ARK436L2SA\_ERK\_6\_3\_4} and \code{ARK436L2SA\_DIRK\_6\_3\_4} for {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}}. -\item {} +\item {} \index{ARK-7-3-4 ARK method}4th-order pair: {\hyperref[Butcher:butcher-ark-7-3-4-e]{\emph{\DUspan{}{ARK-7-3-4 (explicit)}}}} with {\hyperref[Butcher:butcher-ark-7-3-4-i]{\emph{\DUspan{}{ARK-7-3-4 (implicit)}}}}, corresponding to Butcher tables \code{ARK437L2SA\_ERK\_7\_3\_4} and \code{ARK437L2SA\_DIRK\_7\_3\_4} for {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}}. -\item {} +\item {} \index{ARK-8-4-5 ARK method}5th-order pair: {\hyperref[Butcher:butcher-ark-8-4-5-e]{\emph{\DUspan{}{ARK-8-4-5 (explicit)}}}} with {\hyperref[Butcher:butcher-ark-8-4-5-i]{\emph{\DUspan{}{ARK-8-4-5 (implicit)}}}}, corresponding to Butcher tables \code{ARK548L2SA\_ERK\_8\_4\_5} and \code{ARK548L2SA\_ERK\_8\_4\_5} for {\hyperref[ARKStep_c_interface/User_callable:c.ARKStepSetTableNum]{\emph{\code{ARKStepSetTableNum()}}}}. -\item {} +\item {} \index{ARK-8-4-5b ARK method}5th-order pair: {\hyperref[Butcher:butcher-ark-8-4-5b-e]{\emph{\DUspan{}{ARK-8-4-5b (explicit)}}}} with {\hyperref[Butcher:butcher-ark-8-4-5b-i]{\emph{\DUspan{}{ARK-8-4-5b (implicit)}}}}, corresponding to Butcher tables \code{ARK548L2SAb\_ERK\_8\_4\_5} and @@ -44230,21 +44280,21 @@ \chapter{Appendix: SUNDIALS Release History} \label{History:appendix-sundials-release-history}\label{History::doc}\label{History:history} \begin{longtable}{|l|l|l|l|l|l|l|l|} \hline -\textsf{\relax +\textsf{\relax Date -} & \textsf{\relax +} & \textsf{\relax SUNDIALS -} & \textsf{\relax +} & \textsf{\relax ARKode -} & \textsf{\relax +} & \textsf{\relax CVODE -} & \textsf{\relax +} & \textsf{\relax CVODES -} & \textsf{\relax +} & \textsf{\relax IDA -} & \textsf{\relax +} & \textsf{\relax IDAS -} & \textsf{\relax +} & \textsf{\relax KINSOL }\\ \hline\endfirsthead @@ -44252,21 +44302,21 @@ \chapter{Appendix: SUNDIALS Release History} \multicolumn{8}{c}% {{\textsf{\tablename\ \thetable{} -- continued from previous page}}} \\ \hline -\textsf{\relax +\textsf{\relax Date -} & \textsf{\relax +} & \textsf{\relax SUNDIALS -} & \textsf{\relax +} & \textsf{\relax ARKode -} & \textsf{\relax +} & \textsf{\relax CVODE -} & \textsf{\relax +} & \textsf{\relax CVODES -} & \textsf{\relax +} & \textsf{\relax IDA -} & \textsf{\relax +} & \textsf{\relax IDAS -} & \textsf{\relax +} & \textsf{\relax KINSOL }\\ \hline\endhead @@ -44277,849 +44327,815 @@ \chapter{Appendix: SUNDIALS Release History} \endlastfoot -Sep 2019 - & -5.0.0-dev.2 - & -4.0.0-dev.2 - & -5.0.0-dev.2 - & -5.0.0-dev.2 - & -5.0.0-dev.2 - & -4.0.0-dev.2 - & -5.0.0-dev.2 -\\ -\hline -Jun 2019 - & -5.0.0-dev.1 - & -4.0.0-dev.1 - & -5.0.0-dev.1 - & -5.0.0-dev.1 - & -5.0.0-dev.1 - & -4.0.0-dev.1 - & -5.0.0-dev.1 -\\ -\hline -Mar 2019 - & -5.0.0-dev.0 - & -4.0.0-dev.0 - & -5.0.0-dev.0 - & -5.0.0-dev.0 - & -5.0.0-dev.0 - & -4.0.0-dev.0 - & -5.0.0-dev.0 +Oct 2019 + & +5.0.0 + & +4.0.0 + & +5.0.0 + & +5.0.0 + & +5.0.0 + & +4.0.0 + & +5.0.0 \\ \hline Feb 2019 - & + & 4.1.0 - & + & 3.1.0 - & + & 4.1.0 - & + & 4.1.0 - & + & 4.1.0 - & + & 3.1.0 - & + & 4.1.0 \\ \hline Jan 2019 - & + & 4.0.2 - & + & 3.0.2 - & + & 4.0.2 - & + & 4.0.2 - & + & 4.0.2 - & + & 3.0.2 - & + & 4.0.2 \\ \hline Dec 2018 - & + & 4.0.1 - & + & 3.0.1 - & + & 4.0.1 - & + & 4.0.1 - & + & 4.0.1 - & + & 3.0.1 - & + & 4.0.1 \\ \hline Dec 2018 - & + & 4.0.0 - & + & 3.0.0 - & + & 4.0.0 - & + & 4.0.0 - & + & 4.0.0 - & + & 3.0.0 - & + & 4.0.0 \\ \hline Oct 2018 - & + & 3.2.1 - & + & 2.2.1 - & + & 3.2.1 - & + & 3.2.1 - & + & 3.2.1 - & + & 2.2.1 - & + & 3.2.1 \\ \hline Sep 2018 - & + & 3.2.0 - & + & 2.2.0 - & + & 3.2.0 - & + & 3.2.0 - & + & 3.2.0 - & + & 2.2.0 - & + & 3.2.0 \\ \hline Jul 2018 - & + & 3.1.2 - & + & 2.1.2 - & + & 3.1.2 - & + & 3.1.2 - & + & 3.1.2 - & + & 2.1.2 - & + & 3.1.2 \\ \hline May 2018 - & + & 3.1.1 - & + & 2.1.1 - & + & 3.1.1 - & + & 3.1.1 - & + & 3.1.1 - & + & 2.1.1 - & + & 3.1.1 \\ \hline Nov 2017 - & + & 3.1.0 - & + & 2.1.0 - & + & 3.1.0 - & + & 3.1.0 - & + & 3.1.0 - & + & 2.1.0 - & + & 3.1.0 \\ \hline Sep 2017 - & + & 3.0.0 - & + & 2.0.0 - & + & 3.0.0 - & + & 3.0.0 - & + & 3.0.0 - & + & 2.0.0 - & + & 3.0.0 \\ \hline Sep 2016 - & + & 2.7.0 - & + & 1.1.0 - & + & 2.9.0 - & + & 2.9.0 - & + & 2.9.0 - & + & 1.3.0 - & + & 2.9.0 \\ \hline Aug 2015 - & + & 2.6.2 - & + & 1.0.2 - & + & 2.8.2 - & + & 2.8.2 - & + & 2.8.2 - & + & 1.2.2 - & + & 2.8.2 \\ \hline Mar 2015 - & + & 2.6.1 - & + & 1.0.1 - & + & 2.8.1 - & + & 2.8.1 - & + & 2.8.1 - & + & 1.2.1 - & + & 2.8.1 \\ \hline Mar 2015 - & + & 2.6.0 - & + & 1.0.0 - & + & 2.8.0 - & + & 2.8.0 - & + & 2.8.0 - & + & 1.2.0 - & + & 2.8.0 \\ \hline Mar 2012 - & + & 2.5.0 - & + & -- - & + & 2.7.0 - & + & 2.7.0 - & + & 2.7.0 - & + & 1.1.0 - & + & 2.7.0 \\ \hline May 2009 - & + & 2.4.0 - & + & -- - & + & 2.6.0 - & + & 2.6.0 - & + & 2.6.0 - & + & 1.0.0 - & + & 2.6.0 \\ \hline Nov 2006 - & + & 2.3.0 - & + & -- - & + & 2.5.0 - & + & 2.5.0 - & + & 2.5.0 - & + & -- - & + & 2.5.0 \\ \hline Mar 2006 - & + & 2.2.0 - & + & -- - & + & 2.4.0 - & + & 2.4.0 - & + & 2.4.0 - & + & -- - & + & 2.4.0 \\ \hline May 2005 - & + & 2.1.1 - & + & -- - & + & 2.3.0 - & + & 2.3.0 - & + & 2.3.0 - & + & -- - & + & 2.3.0 \\ \hline Apr 2005 - & + & 2.1.0 - & + & -- - & + & 2.3.0 - & + & 2.2.0 - & + & 2.3.0 - & + & -- - & + & 2.3.0 \\ \hline Mar 2005 - & + & 2.0.2 - & + & -- - & + & 2.2.2 - & + & 2.1.2 - & + & 2.2.2 - & + & -- - & + & 2.2.2 \\ \hline Jan 2005 - & + & 2.0.1 - & + & -- - & + & 2.2.1 - & + & 2.1.1 - & + & 2.2.1 - & + & -- - & + & 2.2.1 \\ \hline Dec 2004 - & + & 2.0.0 - & + & -- - & + & 2.2.0 - & + & 2.1.0 - & + & 2.2.0 - & + & -- - & + & 2.2.0 \\ \hline Jul 2002 - & + & 1.0.0 - & + & -- - & + & 2.0.0 - & + & 1.0.0 - & + & 2.0.0 - & + & -- - & + & 2.0.0 \\ \hline Mar 2002 - & + & -- - & + & -- - & + & 1.0.0 \footnote{ CVODE and PVODE combined } - & + & -- - & + & -- - & + & -- - & + & -- \\ \hline Feb 1999 - & + & -- - & + & -- - & + & -- - & + & -- - & + & 1.0.0 \footnote{ IDA written } - & + & -- - & + & -- \\ \hline Aug 1998 - & + & -- - & + & -- - & + & -- - & + & -- - & + & -- - & + & -- - & + & 1.0.0 \footnote{ KINSOL written } \\ \hline Jul 1997 - & + & -- - & + & -- - & + & 1.0.0 \footnote{ PVODE written } - & + & -- - & + & -- - & + & -- - & + & -- \\ \hline Sep 1994 - & + & -- - & + & -- - & + & 1.0.0 \footnote{ CVODE written } - & + & -- - & + & -- - & + & -- - & + & -- \\ \hline\end{longtable} \phantomsection\label{References:references} \begin{thebibliography}{SuperLUDIST} -\bibitem[A1965]{A1965}{\phantomsection\label{References:a1965} +\bibitem[A1965]{A1965}{\phantomsection\label{References:a1965} D.G. Anderson, Iterative Procedures for Nonlinear Integral Equations, \emph{J. Assoc. Comput. Machinery}, 12:547-560, 1965. } -\bibitem[B1985]{B1985}{\phantomsection\label{References:b1985} +\bibitem[B1985]{B1985}{\phantomsection\label{References:b1985} Bank et al., Transient Simulation of Silicon Devices and Circuits, \emph{IEEE Trans. CAD}, 4:436-451, 1985. } -\bibitem[B1983]{B1983}{\phantomsection\label{References:b1983} +\bibitem[B1983]{B1983}{\phantomsection\label{References:b1983} S.R. Billington, Type-Insensitive Codes for the Solution of Stiff and Nonstiff Systems of Ordinary Differential Equations, \emph{in: Master Thesis, University of Manchester, United Kingdom}, 1983. } -\bibitem[BS1989]{BS1989}{\phantomsection\label{References:bs1989} +\bibitem[BS1989]{BS1989}{\phantomsection\label{References:bs1989} P. Bogacki and L.F. Shampine. A 3(2) pair of Runge–Kutta formulas, \emph{Appl. Math. Lett.}, 2:321–325, 1989. } -\bibitem[B1987]{B1987}{\phantomsection\label{References:b1987} +\bibitem[B1987]{B1987}{\phantomsection\label{References:b1987} P.N. Brown. A local convergence theory for combined inexact-Newton/finite difference projection methods. \emph{SIAM J. Numer. Anal.}, 24:407-434, 1987. } -\bibitem[BBH1989]{BBH1989}{\phantomsection\label{References:bbh1989} +\bibitem[BBH1989]{BBH1989}{\phantomsection\label{References:bbh1989} P.N. Brown, G.D. Byrne and A.C. Hindmarsh. VODE, a Variable-Coefficient ODE Solver. \emph{SIAM J. Sci. Stat. Comput.}, 10:1038-1051, 1989. } -\bibitem[BH1989]{BH1989}{\phantomsection\label{References:bh1989} +\bibitem[BH1989]{BH1989}{\phantomsection\label{References:bh1989} P.N. Brown and A.C. Hindmarsh. Reduced Storage Matrix Methods in Stiff ODE Systems. \emph{J. Appl. Math. \& Comp.}, 31:49-91, 1989. } -\bibitem[BS1990]{BS1990}{\phantomsection\label{References:bs1990} +\bibitem[BS1990]{BS1990}{\phantomsection\label{References:bs1990} P.N. Brown and Y. Saad. Hybrid Krylov Methods for Nonlinear Systems of Equations. \emph{SIAM J. Sci. Stat. Comput.}, 11:450-481, 1990. } -\bibitem[B2008]{B2008}{\phantomsection\label{References:b2008} +\bibitem[B2008]{B2008}{\phantomsection\label{References:b2008} J.C. Butcher, Numerical Methods for Ordinary Differential Equations. Wiley, 2nd edition, Chicester, England, 2008. } -\bibitem[B1992]{B1992}{\phantomsection\label{References:b1992} +\bibitem[B1992]{B1992}{\phantomsection\label{References:b1992} G.D. Byrne. Pragmatic Experiments with Krylov Methods in the Stiff ODE Setting. In J.R. Cash and I. Gladwell, editors, \emph{Computational Ordinary Differential Equations}, pp. 323-356, Oxford University Press, 1992. } -\bibitem[C1979]{C1979}{\phantomsection\label{References:c1979} +\bibitem[C1979]{C1979}{\phantomsection\label{References:c1979} J.R. Cash. Diagonally Implicit Runge-Kutta Formulae with Error Estimates. \emph{IMA J Appl Math}, 24:293-301, 1979. } -\bibitem[CK1990]{CK1990}{\phantomsection\label{References:ck1990} +\bibitem[CK1990]{CK1990}{\phantomsection\label{References:ck1990} J.R. Cash and A.H. Karp. A variable order Runge-Kutta method for initial value problems with rapidly varying right-hand sides, \emph{ACM Trans. Math. Soft.}, 16:201-222, 1990. } -\bibitem[CGM2014]{CGM2014}{\phantomsection\label{References:cgm2014} +\bibitem[CGM2014]{CGM2014}{\phantomsection\label{References:cgm2014} J. Cheng, M. Grossman and T. McKercher. Professional Cuda C Programming. John Wiley \& Sons, 2014. } -\bibitem[cuSOLVER]{cuSOLVER}{\phantomsection\label{References:cusolver} +\bibitem[cuSOLVER]{cuSOLVER}{\phantomsection\label{References:cusolver} \href{https://docs.nvidia.com/cuda/cusolver/index.html}{NVIDIA cuSOLVER Documentation}. } -\bibitem[DP1980]{DP1980}{\phantomsection\label{References:dp1980} +\bibitem[DP1980]{DP1980}{\phantomsection\label{References:dp1980} J.R. Dormand and P.J. Prince. A family of embedded Runge-Kutta formulae, \emph{J. Comput. Appl. Math.} 6:19–26, 1980. } -\bibitem[DP2010]{DP2010}{\phantomsection\label{References:dp2010} +\bibitem[DP2010]{DP2010}{\phantomsection\label{References:dp2010} T. Davis and E. Palamadai Natarajan. Algortithm 907: KLU, a direct sparse solver for circuit simulation problems. \emph{ACM Trans. Math. Soft.}, 37, 2010. } -\bibitem[DES1982]{DES1982}{\phantomsection\label{References:des1982} +\bibitem[DES1982]{DES1982}{\phantomsection\label{References:des1982} R.S. Dembo, S.C. Eisenstat and T. Steihaug. Inexact Newton Methods. \emph{SIAM J. Numer. Anal.}, 19:400-408, 1982. } -\bibitem[DGL1999]{DGL1999}{\phantomsection\label{References:dgl1999} +\bibitem[DGL1999]{DGL1999}{\phantomsection\label{References:dgl1999} J.W. Demmel, J.R. Gilbert and X.S. Li. An Asynchronous Parallel Supernodal Algorithm for Sparse Gaussian Elimination. \emph{SIAM J. Matrix Analysis and Applications}, 20:915-952, 1999. } -\bibitem[DS1996]{DS1996}{\phantomsection\label{References:ds1996} +\bibitem[DS1996]{DS1996}{\phantomsection\label{References:ds1996} J.E. Dennis and R.B. Schnabel. Numerical Methods for Unconstrained Optimization and Nonlinear Equations. SIAM, Philadelphia, 1996. } -\bibitem[F2015]{F2015}{\phantomsection\label{References:f2015} +\bibitem[F2015]{F2015}{\phantomsection\label{References:f2015} R. Falgout and U.M. Yang. Hypre user's manual. \emph{LLNL Technical Report}, 2015. } -\bibitem[FS2009]{FS2009}{\phantomsection\label{References:fs2009} +\bibitem[FS2009]{FS2009}{\phantomsection\label{References:fs2009} H. Fang and Y. Saad. Two classes of secant methods for nonlinear acceleration. \emph{Numer. Linear Algebra Appl.}, 16:197-21, 2009. } -\bibitem[F1969]{F1969}{\phantomsection\label{References:f1969} +\bibitem[F1969]{F1969}{\phantomsection\label{References:f1969} E. Fehlberg. Low-order classical Runge-Kutta formulas with step size control and their application to some heat transfer problems. \emph{NASA Technical Report 315}, 1969. } -\bibitem[F1993]{F1993}{\phantomsection\label{References:f1993} +\bibitem[F1993]{F1993}{\phantomsection\label{References:f1993} R.W. Freund. A Transpose-Free Quasi-Minimal Residual Algorithm for Non-Hermitian Linear Systems. \emph{SIAM J. Sci. Comp.}, 14:470-482, 1993. } -\bibitem[G1991]{G1991}{\phantomsection\label{References:g1991} +\bibitem[G1991]{G1991}{\phantomsection\label{References:g1991} K. Gustafsson. Control theoretic techniques for stepsize selection in explicit Runge-Kutta methods. \emph{ACM Trans. Math. Soft.}, 17:533-554, 1991. } -\bibitem[G1994]{G1994}{\phantomsection\label{References:g1994} +\bibitem[G1994]{G1994}{\phantomsection\label{References:g1994} K. Gustafsson. Control-theoretic techniques for stepsize selection in implicit Runge-Kutta methods. \emph{ACM Trans. Math. Soft.} 20:496-512, 1994. } -\bibitem[GDL2007]{GDL2007}{\phantomsection\label{References:gdl2007} +\bibitem[GDL2007]{GDL2007}{\phantomsection\label{References:gdl2007} L. Grigori, J.W. Demmel, and X.S. Li. Parallel Symbolic Factorization for Sparse LU with Static Pivoting. \emph{SIAM J. Scientific Comptuing}, 29:1289-1314, 2007. } -\bibitem[HW1993]{HW1993}{\phantomsection\label{References:hw1993} +\bibitem[HW1993]{HW1993}{\phantomsection\label{References:hw1993} E. Hairer, S. Norsett and G. Wanner. Solving Ordinary Differential Equations I. \emph{Springer Series in Computational Mathematics}, vol. 8, 1993. } -\bibitem[HW1996]{HW1996}{\phantomsection\label{References:hw1996} +\bibitem[HW1996]{HW1996}{\phantomsection\label{References:hw1996} E. Hairer and G. Wanner. Solving Ordinary Differential Equations II. \emph{Springer Series in Computational Mathematics}, vol. 14, 1996. } -\bibitem[HS1952]{HS1952}{\phantomsection\label{References:hs1952} +\bibitem[HS1952]{HS1952}{\phantomsection\label{References:hs1952} M.R. Hestenes and E. Stiefel. Methods of Conjugate Gradients for Solving Linear Systems. \emph{J. Research of the National Bureau of Standards}, 49:409-436, 1952. } -\bibitem[HS1980]{HS1980}{\phantomsection\label{References:hs1980} +\bibitem[HS1980]{HS1980}{\phantomsection\label{References:hs1980} K.L. Hiebert and L.F. Shampine. Implicitly Defined Output Points for Solutions of ODEs. Technical Report SAND80-0180, Sandia National Laboratories, February 1980. } -\bibitem[H2000]{H2000}{\phantomsection\label{References:h2000} +\bibitem[H2000]{H2000}{\phantomsection\label{References:h2000} A.C. Hindmarsh. The PVODE and IDA Algorithms. Technical Report UCRL-ID-141558, LLNL, 2000. } -\bibitem[HS2017]{HS2017}{\phantomsection\label{References:hs2017} +\bibitem[HS2017]{HS2017}{\phantomsection\label{References:hs2017} A.C. Hindmarsh and R. Serban. User Documentation for CVODE -v5.0.0-dev.2. Technical Report UCRL-SM-208108, LLNL, 2019. +v5.0.0. Technical Report UCRL-SM-208108, LLNL, 2019. } -\bibitem[HSR2017]{HSR2017}{\phantomsection\label{References:hsr2017} +\bibitem[HSR2017]{HSR2017}{\phantomsection\label{References:hsr2017} A.C. Hindmarsh, R. Serban and D.R. Reynolds. Example -Programs for CVODE v5.0.0-dev.2. Technical Report +Programs for CVODE v5.0.0. Technical Report UCRL-SM-208110, LLNL, 2019. } -\bibitem[HT1998]{HT1998}{\phantomsection\label{References:ht1998} +\bibitem[HT1998]{HT1998}{\phantomsection\label{References:ht1998} A.C. Hindmarsh and A.G. Taylor. PVODE and KINSOL: Parallel Software for Differential and Nonlinear Systems. Technical Report UCRL-IL-129739, LLNL, February 1998. } -\bibitem[HK2014]{HK2014}{\phantomsection\label{References:hk2014} +\bibitem[HK2014]{HK2014}{\phantomsection\label{References:hk2014} R.D. Hornung and J.A. Keasler. The RAJA Portability Layer: Overview and Status. Technical Report LLNL-TR-661403, LLNL, September 2014. } -\bibitem[JPE2019]{JPE2019}{\phantomsection\label{References:jpe2019} +\bibitem[JPE2019]{JPE2019}{\phantomsection\label{References:jpe2019} S.R. Johnson, A. Prokopenko, and K. J. Evans. Automated Fortran-C++ bindings for Large-Scale Scientific Applications. arXiv:1904.02546 {[}cs{]}, Apr. 2019. } -\bibitem[K1995]{K1995}{\phantomsection\label{References:k1995} +\bibitem[K1995]{K1995}{\phantomsection\label{References:k1995} C.T. Kelley. Iterative Methods for Solving Linear and Nonlinear Equations. SIAM, Philadelphia, 1995. } -\bibitem[KC2003]{KC2003}{\phantomsection\label{References:kc2003} +\bibitem[KC2003]{KC2003}{\phantomsection\label{References:kc2003} C.A. Kennedy and M.H. Carpenter. Additive Runge-Kutta schemes for convection-diffusion-reaction equations. \emph{Appl. Numer. Math.}, 44:139-181, 2003. } -\bibitem[KC2019]{KC2019}{\phantomsection\label{References:kc2019} +\bibitem[KC2019]{KC2019}{\phantomsection\label{References:kc2019} C.A. Kennedy and M.H. Carpenter. Higher-order additive Runge–Kutta schemes for ordinary differential equations. \emph{Appl. Numer. Math.}, 136:183-205, 2019. } -\bibitem[K2004]{K2004}{\phantomsection\label{References:k2004} +\bibitem[K2004]{K2004}{\phantomsection\label{References:k2004} A. Kv\{ae\}rno. Singly Diagonally Implicit Runge-Kutta Methods with an Explicit First Stage. \emph{BIT Numer. Math.}, 44:489-502, 2004. } -\bibitem[KLU]{KLU}{\phantomsection\label{References:klu} +\bibitem[KLU]{KLU}{\phantomsection\label{References:klu} \href{http://faculty.cse.tamu.edu/davis/suitesparse.html}{KLU Sparse Matrix Factorization Library}. } -\bibitem[L2005]{L2005}{\phantomsection\label{References:l2005} +\bibitem[L2005]{L2005}{\phantomsection\label{References:l2005} X.S. Li. An Overview of SuperLU: Algorithms, Implementation, and User Interface. \emph{ACM Trans. Math. Soft.}, 31:302-325, 2005. } -\bibitem[LD2003]{LD2003}{\phantomsection\label{References:ld2003} +\bibitem[LD2003]{LD2003}{\phantomsection\label{References:ld2003} X.S. Li. and J.W. Demmel. A Scalable Distributed-Memory Sparse Direct Solver for Unsymmetric Linear Systems. \emph{ACM Trans. Math. Soft.}, 29:110-140, 2003. } -\bibitem[LWWY2012]{LWWY2012}{\phantomsection\label{References:lwwy2012} +\bibitem[LWWY2012]{LWWY2012}{\phantomsection\label{References:lwwy2012} P.A. Lott, H.F. Walker, C.S. Woodward and U.M. Yang. An Accelerated Picard Method for Nonlinear Systems Related to Variably Saturated Flow, \emph{Adv. Wat. Resour.}, 38:92-101, 2012. } -\bibitem[R2018]{R2018}{\phantomsection\label{References:r2018} +\bibitem[R2018]{R2018}{\phantomsection\label{References:r2018} D.R. Reynolds. ARKode Example Documentation. Technical Report, Southern Methodist University Center for Scientific Computation, 2019. } -\bibitem[SS1986]{SS1986}{\phantomsection\label{References:ss1986} +\bibitem[SS1986]{SS1986}{\phantomsection\label{References:ss1986} Y. Saad and M.H. Schultz. GMRES: A Generalized Minimal Residual Algorithm for Solving Nonsymmetric Linear Systems. \emph{SIAM J. Sci. Stat. Comp.}, 7:856-869, 1986. } -\bibitem[S1993]{S1993}{\phantomsection\label{References:s1993} +\bibitem[S1993]{S1993}{\phantomsection\label{References:s1993} Y. Saad. A flexible inner-outer preconditioned GMRES algorithm. \emph{SIAM J. Sci. Comput.}, 14:461-469, 1993. } -\bibitem[SA2002]{SA2002}{\phantomsection\label{References:sa2002} +\bibitem[SA2002]{SA2002}{\phantomsection\label{References:sa2002} A. Sayfy and A. Aburub. Embedded Additive Runge-Kutta Methods. \emph{Intern. J. Computer Math.}, 79:945-953, 2002. } -\bibitem[SKAW2009]{SKAW2009}{\phantomsection\label{References:skaw2009} +\bibitem[SKAW2009]{SKAW2009}{\phantomsection\label{References:skaw2009} M. Schlegel, O. Knoth, M. Arnold, and R. Wolke. Multirate Runge--Kutta schemes for advection equations. \emph{J. Comput. Appl. Math.}, 226:345-357, 2009. } -\bibitem[SKAW2012a]{SKAW2012a}{\phantomsection\label{References:skaw2012a} +\bibitem[SKAW2012a]{SKAW2012a}{\phantomsection\label{References:skaw2012a} M. Schlegel, O. Knoth, M. Arnold, and R. Wolke. Implementation of multirate time integration methods for air pollution modelling. \emph{GMD}, 5:1395-1405, 2012. } -\bibitem[SKAW2012b]{SKAW2012b}{\phantomsection\label{References:skaw2012b} +\bibitem[SKAW2012b]{SKAW2012b}{\phantomsection\label{References:skaw2012b} M. Schlegel, O. Knoth, M. Arnold, and R. Wolke. Numerical solution of multiscale problems in atmospheric modeling. \emph{Appl. Numer. Math.}, 62:1531-1542, 2012. } -\bibitem[S1998]{S1998}{\phantomsection\label{References:s1998} +\bibitem[S1998]{S1998}{\phantomsection\label{References:s1998} G. Soderlind. The automatic control of numerical integration. \emph{CWI Quarterly}, 11:55-74, 1998. } -\bibitem[S2003]{S2003}{\phantomsection\label{References:s2003} +\bibitem[S2003]{S2003}{\phantomsection\label{References:s2003} G. Soderlind. Digital filters in adaptive time-stepping. \emph{ACM Trans. Math. Soft.}, 29:1-26, 2003. } -\bibitem[S2006]{S2006}{\phantomsection\label{References:s2006} +\bibitem[S2006]{S2006}{\phantomsection\label{References:s2006} G. Soderlind. Time-step selection algorithms: Adaptivity, control and signal processing. \emph{Appl. Numer. Math.}, 56:488-502, 2006. } -\bibitem[SLUUG1999]{SLUUG1999}{\phantomsection\label{References:sluug1999} +\bibitem[SLUUG1999]{SLUUG1999}{\phantomsection\label{References:sluug1999} X.S. Li, J.W. Demmel, J.R. Gilbert, L. Grigori, M. Shao and I. Yamazaki. SuperLU Users' Guide. 1999. } -\bibitem[SuperLUDIST]{SuperLUDIST}{\phantomsection\label{References:superludist} +\bibitem[SuperLUDIST]{SuperLUDIST}{\phantomsection\label{References:superludist} \href{http://crd-legacy.lbl.gov/~xiaoye/SuperLU/}{SuperLU\_DIST Parallel Sparse Matrix Factorization Library}. } -\bibitem[SuperLUMT]{SuperLUMT}{\phantomsection\label{References:superlumt} +\bibitem[SuperLUMT]{SuperLUMT}{\phantomsection\label{References:superlumt} \href{http://crd-legacy.lbl.gov/~xiaoye/SuperLU/}{SuperLU\_MT Threaded Sparse Matrix Factorization Library}. } -\bibitem[V1992]{V1992}{\phantomsection\label{References:v1992} +\bibitem[V1992]{V1992}{\phantomsection\label{References:v1992} H.A. Van Der Vorst. Bi-CGSTAB: A Fast and Smoothly Converging Variant of Bi-CG for the Solution of Nonsymmetric Linear Systems. \emph{SIAM J. Sci. Stat. Comp.}, 13:631-644, 1992. } -\bibitem[V1978]{V1978}{\phantomsection\label{References:v1978} +\bibitem[V1978]{V1978}{\phantomsection\label{References:v1978} J.H. Verner. Explicit Runge-Kutta methods with estimates of the local truncation error. \emph{SIAM J. Numer. Anal.}, 15:772-790, 1978. } -\bibitem[WN2011]{WN2011}{\phantomsection\label{References:wn2011} +\bibitem[WN2011]{WN2011}{\phantomsection\label{References:wn2011} H.F. Walker and P. Ni. Anderson acceleration for fixed-point iterations. \emph{SIAM J. Numer. Anal.}, 49:1715-1735, 2011. } -\bibitem[KW1998]{KW1998}{\phantomsection\label{References:kw1998} +\bibitem[KW1998]{KW1998}{\phantomsection\label{References:kw1998} O. Knoth and R. Wolke. Implicit-explicit Runge-Kutta methods for computing atmospheric reactive flows. \emph{Appl. Numer. Math.}, 28(2):327-341, 1998. } -\bibitem[Z1963]{Z1963}{\phantomsection\label{References:z1963} +\bibitem[Z1963]{Z1963}{\phantomsection\label{References:z1963} J.A. Zonneveld. Automatic integration of ordinary differential equations. \emph{Report R743, Mathematisch Centrum}, Postbus 4079, 1009AB Amsterdam, 1963. diff --git a/doc/arkode/ARKode_example.tex b/doc/arkode/ARKode_example.tex index e00db7e663..73b0bd02fc 100644 --- a/doc/arkode/ARKode_example.tex +++ b/doc/arkode/ARKode_example.tex @@ -67,7 +67,7 @@ {\centerline{\includegraphics[width=0.5\textwidth]{doc_logo_blue.pdf}}} \vfill } -\release{4.0.0-dev.2} +\release{4.0.0} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/doc/arkode/SphinxDocs/examples/source/References.rst b/doc/arkode/SphinxDocs/examples/source/References.rst index 6be1b46596..df7fd10309 100644 --- a/doc/arkode/SphinxDocs/examples/source/References.rst +++ b/doc/arkode/SphinxDocs/examples/source/References.rst @@ -23,8 +23,8 @@ ========== .. [HSR2017] A.C. Hindmarsh, R. Serban and D.R. Reynolds. Example - Programs for CVODE v5.0.0-dev.2. Technical Report + Programs for CVODE v5.0.0. Technical Report UCRL-SM-208110, LLNL, 2019. .. [R2018] D.R. Reynolds. User Documentation for ARKode - v4.0.0-dev.2. Technical Report LLNL-CODE-667205, LLNL, 2019. + v4.0.0. Technical Report LLNL-CODE-667205, LLNL, 2019. diff --git a/doc/arkode/SphinxDocs/examples/source/conf.py b/doc/arkode/SphinxDocs/examples/source/conf.py index fb47597d55..b24260739e 100644 --- a/doc/arkode/SphinxDocs/examples/source/conf.py +++ b/doc/arkode/SphinxDocs/examples/source/conf.py @@ -49,9 +49,9 @@ # built documents. # # The short X.Y version. -version = '4.0.0-dev.2' +version = '4.0.0' # The full version, including alpha/beta/rc tags. -release = '4.0.0-dev.2' +release = '4.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/arkode/SphinxDocs/guide/source/History.rst b/doc/arkode/SphinxDocs/guide/source/History.rst index cf72f38ba8..64e125431f 100644 --- a/doc/arkode/SphinxDocs/guide/source/History.rst +++ b/doc/arkode/SphinxDocs/guide/source/History.rst @@ -23,9 +23,7 @@ Appendix: SUNDIALS Release History ======== =========== =========== =========== =========== =========== =========== =========== Date SUNDIALS ARKode CVODE CVODES IDA IDAS KINSOL ======== =========== =========== =========== =========== =========== =========== =========== -Sep 2019 5.0.0-dev.2 4.0.0-dev.2 5.0.0-dev.2 5.0.0-dev.2 5.0.0-dev.2 4.0.0-dev.2 5.0.0-dev.2 -Jun 2019 5.0.0-dev.1 4.0.0-dev.1 5.0.0-dev.1 5.0.0-dev.1 5.0.0-dev.1 4.0.0-dev.1 5.0.0-dev.1 -Mar 2019 5.0.0-dev.0 4.0.0-dev.0 5.0.0-dev.0 5.0.0-dev.0 5.0.0-dev.0 4.0.0-dev.0 5.0.0-dev.0 +Oct 2019 5.0.0 4.0.0 5.0.0 5.0.0 5.0.0 4.0.0 5.0.0 Feb 2019 4.1.0 3.1.0 4.1.0 4.1.0 4.1.0 3.1.0 4.1.0 Jan 2019 4.0.2 3.0.2 4.0.2 4.0.2 4.0.2 3.0.2 4.0.2 Dec 2018 4.0.1 3.0.1 4.0.1 4.0.1 4.0.1 3.0.1 4.0.1 diff --git a/doc/arkode/SphinxDocs/guide/source/Introduction.rst b/doc/arkode/SphinxDocs/guide/source/Introduction.rst index d4fc730133..6044732d90 100644 --- a/doc/arkode/SphinxDocs/guide/source/Introduction.rst +++ b/doc/arkode/SphinxDocs/guide/source/Introduction.rst @@ -110,123 +110,215 @@ Changes from previous versions Changes in v4.0.0 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The return type of the SUNLinearSolver API function -:c:func:`SUNLinSolLastFlag()` has changed from ``long int`` to ``sunindextype`` -to be consistent with the type used to store row indices in dense and -banded linear solver modules. +**Build system changes** -Added Fortran 2003 interfaces to the ``NVECTOR_MANYVECTOR``, -``NVECTOR_MPIMANYVECTOR`` and ``NVECTOR_MPIPLUSX``. +Increased the minimum required CMake version to 3.5 for most SUNDIALS +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. -Added three new utility N_Vector functions, ``FN_VGetVecAtIndexVectorArray``, -``FN_VSetVecAtIndexVectorArray``, and ``FN_VNewVectorArray``, that are for working -with N_Vector arrays when using the Fortran 2003 interfaces. - -Added a new ``SUNNonlinearSolver`` implementation, ``SUNNonlinsol_PetscSNES``, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the :c:func:`SUNNonlinSolSetConvTestFn` function in the -SUNNonlinearSolver API has been updated to take a ``void*`` data pointer as -input. The supplied data pointer will be passed to the nonlinear solver -convergence test function on each call. - -The definitions of :c:type:`SUNNonlinSolLSetupFn()` and -:c:type:`SUNNonlinSolLSolveFn()` in the SUNNonlinearSolver API have been updated -to remove unused input parameters. - -Support for optional inequality constraints on individual components of the -solution vector has been added the ARKode ERKStep and ARKStep modules. See -the descriptions of :c:func:`ERKStepSetConstraints()` and -:c:func:`ARKStepSetConstraints()` for more details. Note that enabling -constraint handling requires the NVECTOR operations :c:func:`N_VMinQuotient()`, -:c:func:`N_VConstrMask()`, and :c:func:`N_VCompare()` that were not previously -required by ARKode. - -Fixed a bug that would result in a "too much accuracy requested" error when -using fixed time step sizes with explicit methods in some cases. - - -Changes in v4.0.0-dev.2 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The CMake option ``BLAS_ENABLE`` and the variable ``BLAS_LIBRARIES`` have been +removed to simplify builds as SUNDIALS packages do not use BLAS directly. For +third party libraries that require linking to BLAS, the path to the BLAS +library should be included in the ``_LIBRARIES`` variable for the third party +library e.g., ``SUPERLUDIST_LIBRARIES`` when enabling SuperLU_DIST. -Added a new optional operation to the SUNLINEARSOLVER API, ``SUNLinSolGetID``, -that returns a ``SUNLinearSolver_ID`` for identifying the linear solver module. +Fixed a bug in the build system that prevented the PThreads NVECTOR module from +being built. -Made performance improvements to the CUDA NVECTOR. Users who utilize a non --default stream should no longer see default stream synchronizations after -memory transfers. +**NVECTOR module changes** + +Two new functions were added to aid in creating custom NVECTOR objects. The +constructor :c:func:`N_VNewEmpty()` allocates an "empty" generic NVECTOR with +the object's content pointer and the function pointers in the operations +structure initialized to ``NULL``. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the NVECTOR API by ensuring only required operations need to be set. +Additionally, the function :c:func:`N_VCopyOps()` has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the NVECTOR API by ensuring all operations +are copied when cloning objects. + +Two new NVECTOR implementations, NVECTOR_MANYVECTOR and +NVECTOR_MPIMANYVECTOR, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and SUNDIALS +examples. -Added a new constructor to the CUDA NVECTOR that allows a user to provide +One new required vector operation and ten new optional vector operations have +been added to the NVECTOR API. The new required operation, :c:func:`N\_VGetLength()`, +returns the global length of an ``N_Vector``. The optional operations have +been added to support the new NVECTOR_MPIMANYVECTOR implementation. The +operation :c:func:`N_VGetCommunicator()` must be implemented by subvectors that are +combined to create an NVECTOR_MPIMANYVECTOR, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are +:c:func:`N\_VDotProdLocal`, +:c:func:`N\_VMaxNormLocal`, +:c:func:`N\_VMinLocal`, +:c:func:`N\_VL1NormLocal`, +:c:func:`N\_VWSqrSumLocal`, +:c:func:`N\_VWSqrSumMaskLocal`, +:c:func:`N\_VInvTestLocal`, +:c:func:`N\_VConstrMaskLocal`, and +:c:func:`N\_VMinQuotientLocal`. +If an NVECTOR implementation defines any of the local operations as +``NULL``, then the NVECTOR_MPIMANYVECTOR will call standard NVECTOR +operations to complete the computation. + +An additional NVECTOR implementation, NVECTOR_MPIPLUSX, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(*e.g.*, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and SUNDIALS examples. + +The ``*_MPICuda`` and ``*_MPIRaja`` functions have been removed from the +NVECTOR_CUDA and NVECTOR_RAJA implementations respectively. Accordingly, the +``nvector_mpicuda.h``, ``nvector_mpiraja.h``, ``libsundials_nvecmpicuda.lib``, +and ``libsundials_nvecmpicudaraja.lib`` files have been removed. Users should +use the NVECTOR_MPIPLUSX module coupled in conjunction with the NVECTOR_CUDA +or NVECTOR_RAJA modules to replace the functionality. The necessary changes are +minimal and should require few code modifications. See the programs in +``examples/ida/mpicuda`` and ``examples/ida/mpiraja`` for examples of how to +use the NVECTOR_MPIPLUSX module with the NVECTOR_CUDA and NVECTOR_RAJA modules +respectively. + +Fixed a memory leak in the NVECTOR_PETSC module clone function. + +Made performance improvements to the NVECTOR_CUDA module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. + +Added a new constructor to the NVECTOR_CUDA module that allows a user to provide custom allocate and free functions for the vector data array and internal reduction buffer. -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. - -The CMake option ``BLAS_ENABLE`` and the variable ``BLAS_LIBRARIES`` have been -removed to simplify builds as SUNDIALS packages do not use BLAS directly. For -third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the ``_LIBRARIES`` variable for the third party -library e.g., ``SUPERLUDIST_LIBRARIES`` when enabling SuperLU_DIST. +Added new Fortran 2003 interfaces for most NVECTOR modules. See the +:ref:`FortranInterfaces` section for more details. + +Added three new NVECTOR utility functions, +:c:func:`N_VGetVecAtIndexVectorArray()` +:c:func:`N_VSetVecAtIndexVectorArray()`, and +:c:func:`N_VNewVectorArray`, +for working with ``N_Vector`` arrays when using the Fortran 2003 interfaces. + +**SUNMatrix module changes** + +Two new functions were added to aid in creating custom SUNMATRIX objects. The +constructor :c:func:`SUNMatNewEmpty()` allocates an "empty" generic SUNMATRIX with +the object's content pointer and the function pointers in the operations +structure initialized to ``NULL``. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the SUNMATRIX API by ensuring only required operations need to be set. +Additionally, the function :c:func:`SUNMatCopyOps()` has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the SUNMATRIX API by ensuring all operations are +copied when cloning objects. + +A new operation, :c:func:`SUNMatMatvecSetup()`, was added to the SUNMATRIX API. +Users who have implemented custom SUNMATRIX modules will need to at least +update their code to set the corresponding ``ops`` structure member, +``matvecsetup``, to ``NULL``. + +A new operation, :c:func:`SUNMatMatvecSetup()`, was added to the SUNMATRIX API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for SUNMATRIX implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom SUNMATRIX modules will need to at +least update their code to set the corresponding ``ops`` structure member, +``matvecsetup``, to ``NULL``. + +The generic SUNMATRIX API now defines error codes to be returned by +SUNMATRIX operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. + +A new SUNMATRIX (and SUNLINEARSOLVER) implementation was added to +facilitate the use of the SuperLU_DIST library with SUNDIALS. + +Added new Fortran 2003 interfaces for most SUNMATRIX modules. See the +:ref:`FortranInterfaces` section for more details. + +**SUNLinearSolver module changes** + +A new function was added to aid in creating custom SUNLINEARSOLVER objects. +The constructor :c:func:`SUNLinSolNewEmpty()` allocates an "empty" generic +SUNLINEARSOLVER with the object's content pointer and the function pointers +in the operations structure initialized to ``NULL``. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the SUNLINEARSOLVER API by ensuring only required +operations need to be set. -Fixed a bug in the ARKStep time-stepping module that would result in an infinite -loop if the nonlinear solver failed to converge more than the maximum allowed times -during a single step. +The return type of the SUNLINEARSOLVER API function :c:func:`SUNLinSolLastFlag()` +has changed from ``long int`` to ``sunindextype`` to be consistent with the +type used to store row indices in dense and banded linear solver modules. -Added two new 'Get' functions to ARKStep, :c:func:`ARKStepGetCurrentGamma()`, -and :c:func:`ARKStepGetCurrentState`, that may be useful to users who choose -to provide their own nonlinear solver implementation. +Added a new optional operation to the SUNLINEARSOLVER API, +:c:func:`SUNLinSolGetID`, that returns a ``SUNLinearSolver_ID`` for identifying +the linear solver module. -Add two new 'Set' functions to MRIStep, :c:func:`MRIStepSetPreInnerFn()` and -:c:func:`MRIStepSetPostInnerFn()` for performing communication or memory -transfers needed before or after the inner integration. +The SUNLINEARSOLVER API has been updated to make the initialize and setup +functions optional. -The reinitialization functions :c:func:`ERKStepReInit()`, -:c:func:`ARKStepReInit()`, and :c:func:`MRIStepReInit()` have been updated to -retain the minimum and maxiumum step size values from before reinitialization -rather than resetting them to the default values. +A new SUNLINEARSOLVER (and SUNMATRIX) implementation was added to +facilitate the use of the SuperLU_DIST library with SUNDIALS. Added a new SUNLinearSolver implementation, ``SUNLinearSolver_cuSolverSp_batchQR``, which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently solving block diagonal linear systems on NVIDIA GPUs. + Added three new accessor functions to the SUNLinSol_KLU module, :c:func:`SUNLinSol_KLUGetSymbolic()`, :c:func:`SUNLinSol_KLUGetNumeric()`, and :c:func:`SUNLinSol_KLUGetCommon()`, to provide user access to the underlying KLU solver structures. +Added new Fortran 2003 interfaces for most SUNLINEARSOLVER modules. See the +:ref:`FortranInterfaces` section for more details. +**SUNNonlinearSolver module changes** -Changes in v4.0.0-dev.1 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A new function was added to aid in creating custom SUNNONLINEARSOLVER +objects. The constructor :c:func:`SUNNonlinSolNewEmpty()` allocates an "empty" +generic SUNNONLINEARSOLVER with the object's content pointer and the function +pointers in the operations structure initialized to ``NULL``. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the SUNNONLINEARSOLVER API by ensuring only +required operations need to be set. -Several new functions were added to aid in creating custom NVECTOR, SUNMATRIX, -SUNLINEARSOLVER, and SUNNONLINEARSOLVER objects. The constructors -:c:func:`N_VNewEmpty()`, :c:func:`SUNMatNewEmpty()`, -:c:func:`SUNLinSolNewEmpty()`, and :c:func:`SUNNonlinSolNewEmpty()` allocate -"empty" generic NVECTOR, SUNMATRIX, SUNLINEARSOLVER, and SUNNONLINEARSOLVER -objects respectively with the object's content pointer and the function pointers -in the operations structure initialized to ``NULL``. When used in the -constructor for custom objects these functions will ease the introduction of any -new optional operations to the NVECTOR, SUNMATRIX, SUNLINEARSOLVER, or -SUNNONLINEARSOLVER APIs by ensuring only required operations need to be -set. Additionally, the functions :c:func:`N_VCopyOps()` and -:c:func:`SUNMatCopyOps()` have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the NVECTOR or SUNMATRIX APIs by -ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. +To facilitate the use of user supplied nonlinear solver convergence test +functions the :c:func:`SUNNonlinSolSetConvTestFn()` function in the +SUNNONLINEARSOLVER API has been updated to take a ``void*`` data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. -A new linear solver interface function :c:func:`ARKLsLinSysFn` was added as an -alternative method for evaluating the linear system :math:`A = M - \gamma J`. +The inputs values passed to the first two inputs of the :c:func:`SUNNonlinSolSolve()` +function in the SUNNONLINEARSOLVER have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of :c:type:`SUNNonlinSolLSetupFn` and :c:type:`SUNNonlinSolLSolveFn` +in the SUNNONLINEARSOLVER API have been updated to remove unused input +parameters. -The ARKLS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type ``SUNLINEARSOLVER_DIRECT``. +Added a new ``SUNNonlinearSolver`` implementation, ``SUNNonlinsol_PetscSNES``, +which interfaces to the PETSc SNES nonlinear solver API. + +Added new Fortran 2003 interfaces for most SUNNONLINEARSOLVER modules. See the +:ref:`FortranInterfaces` section for more details. + +**ARKode changes** + +The MRIStep module has been updated to support explicit, implicit, or IMEX +methods as the fast integrator using the ARKStep module. As a result some +function signatures have been changed including :c:func:`MRIStepCreate` which +now takes an ARKStep memory structure for the fast integration as an input. + +Fixed a bug in the ARKStep time-stepping module that would result in an infinite +loop if the nonlinear solver failed to converge more than the maximum allowed times +during a single step. + +Fixed a bug that would result in a "too much accuracy requested" error when +using fixed time step sizes with explicit methods in some cases. Fixed a bug in ARKStep where the mass matrix linear solver setup function was not called in the Matrix-free case. @@ -235,36 +327,12 @@ Fixed a minor bug in ARKStep where an incorrect flag is reported when an error occurs in the mass matrix setup or Jacobian-vector product setup functions. -Fixed a bug in the build system that prevented the PThreads NVECTOR module from -being built. - -Fixed a memory leak in the NVECTOR_PETSC clone function. - Fixed a memeory leak in FARKODE when not using the default nonlinear solver. -Added two new embedded ARK methods of orders 4 and 5 to ARKode (from [KC2019]_). - -The ManyVector NVECTOR module has been split into two versions: one -that requires MPI (MPIManyVector) and another that does not use MPI at -all (ManyVector). The associated example problems have been similarly -updated to reflect this new structure. - -An additional NVECTOR implementation, NVECTOR_MPIPLUSX, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and SUNDIALS -examples. - -The \*_MPICuda and \*_MPIRaja functions were removed from the NVECTOR_CUDA and -NVECTOR_RAJA implementations respectively. Accordingly, the ``nvector_mpicuda.h``, -``nvector_mpiraja.h``, ``libsundials_nvecmpicuda.lib``, and ``libsundials_nvecmpicudaraja.lib`` -files have been removed. Users should use the NVECTOR_MPIPLUSX module coupled with -the NVECTOR_CUDA or NVECTOR_RAJA to replace the functionality. The necessary changes -are minimal and should require few code modifications. - -A new Fortran 2003 interface to ARKode was added. This includes Fortran 2003 interfaces -to the ARKStep, ERKStep, and MRIStep time-stepping modules as well as all generic SUNDIALS -types (i.e. NVECTOR, SUNMATRIX, SUNLINEARSOLVER, SUNNONLINEARSOLVER), and many of the module -implementations. See Section :ref:`FortranInterfaces` for more details. +The reinitialization functions :c:func:`ERKStepReInit()`, +:c:func:`ARKStepReInit()`, and :c:func:`MRIStepReInit()` have been updated to +retain the minimum and maxiumum step size values from before reinitialization +rather than resetting them to the default values. Removed extraneous calls to :c:func:`N_VMin()` for simulations where the scalar valued absolute tolerance, or all entries of the @@ -272,54 +340,36 @@ vector-valued absolute tolerance array, are strictly positive. In this scenario, ARKode will remove at least one global reduction per time step. -Changes in v4.0.0-dev.0 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The ARKLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type ``SUNLINEARSOLVER_DIRECT``. + +A new linear solver interface function :c:func:`ARKLsLinSysFn` was added as an +alternative method for evaluating the linear system :math:`A = M - \gamma J`. + +Added two new embedded ARK methods of orders 4 and 5 to ARKode (from [KC2019]_). + +Support for optional inequality constraints on individual components of the +solution vector has been added the ARKode ERKStep and ARKStep modules. See +the descriptions of :c:func:`ERKStepSetConstraints()` and +:c:func:`ARKStepSetConstraints()` for more details. Note that enabling +constraint handling requires the NVECTOR operations :c:func:`N_VMinQuotient()`, +:c:func:`N_VConstrMask()`, and :c:func:`N_VCompare()` that were not previously +required by ARKode. + +Added two new 'Get' functions to ARKStep, :c:func:`ARKStepGetCurrentGamma()`, +and :c:func:`ARKStepGetCurrentState`, that may be useful to users who choose +to provide their own nonlinear solver implementation. + +Add two new 'Set' functions to MRIStep, :c:func:`MRIStepSetPreInnerFn()` and +:c:func:`MRIStepSetPostInnerFn()` for performing communication or memory +transfers needed before or after the inner integration. + +A new Fortran 2003 interface to ARKode was added. This includes Fortran 2003 interfaces +to the ARKStep, ERKStep, and MRIStep time-stepping modules. See the +:ref:`FortranInterfaces` section for more details. -An additional NVECTOR implementation, NVECTOR_MANYVECTOR, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see the -Section :ref:`NVectors.ManyVector` for more details). This -implementation is accompanied by additions to user documentation and -SUNDIALS examples. - -Eleven new optional vector operations have been added to the NVECTOR API to -support the new NVECTOR_MANYVECTOR implementation (see the Chapter :ref:`NVectors` -for more details). Two of the operations, :c:func:`N_VGetCommunicator()` and -:c:func:`N_VGetLength()`, must be implemented by subvectors that are combined to -create an NVECTOR_MANYVECTOR, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are -:c:func:`N_VDotProdLocal()`, -:c:func:`N_VMaxNormLocal()`, -:c:func:`N_VMinLocal()`, -:c:func:`N_VL1NormLocal()`, -:c:func:`N_VWSqrSumLocal()`, -:c:func:`N_VWSqrSumMaskLocal()`, -:c:func:`N_VInvTestLocal()`, -:c:func:`N_VConstrMaskLocal()`, and -:c:func:`N_VMinQuotientLocal()`. -If an NVECTOR implementation defines any of the local operations as ``NULL``, -then the NVECTOR_MANYVECTOR will call standard NVECTOR operations to complete -the computation. - -A new SUNMatrix and SUNLinearSolver implementation was added to facilitate -the use of the SuperLU_DIST library with SUNDIALS. - -A new operation, ``SUNMatMatvecSetup``, was added to the SUNMatrix API. Users -who have implemented custom ``SUNMatrix`` modules will need to at least update -their code to set the corresponding ops structure member, ``matvecsetup``, to ``NULL``. - -The generic SUNMatrix API now defines error codes to be returned by SUNMatrix operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. -The MRIStep module has been updated to support explicit, implicit, or IMEX -methods as the fast integrator using the ARKStep module. As a result some -function signatures have been changed including :c:func:`MRIStepCreate` which -now takes an ARKStep memory structure for the fast integration as an input. Changes in v3.1.0 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/arkode/SphinxDocs/guide/source/References.rst b/doc/arkode/SphinxDocs/guide/source/References.rst index aa90352e5a..14b526cd93 100644 --- a/doc/arkode/SphinxDocs/guide/source/References.rst +++ b/doc/arkode/SphinxDocs/guide/source/References.rst @@ -140,10 +140,10 @@ Report UCRL-ID-141558, LLNL, 2000. .. [HS2017] A.C. Hindmarsh and R. Serban. User Documentation for CVODE - v5.0.0-dev.2. Technical Report UCRL-SM-208108, LLNL, 2019. + v5.0.0. Technical Report UCRL-SM-208108, LLNL, 2019. .. [HSR2017] A.C. Hindmarsh, R. Serban and D.R. Reynolds. Example - Programs for CVODE v5.0.0-dev.2. Technical Report + Programs for CVODE v5.0.0. Technical Report UCRL-SM-208110, LLNL, 2019. .. [HT1998] A.C. Hindmarsh and A.G. Taylor. PVODE and KINSOL: diff --git a/doc/arkode/SphinxDocs/guide/source/conf.py b/doc/arkode/SphinxDocs/guide/source/conf.py index 053e28a370..afd71cd9dc 100644 --- a/doc/arkode/SphinxDocs/guide/source/conf.py +++ b/doc/arkode/SphinxDocs/guide/source/conf.py @@ -50,9 +50,9 @@ # built documents. # # The short X.Y version. -version = '4.0.0-dev.2' +version = '4.0.0' # The full version, including alpha/beta/rc tags. -release = '4.0.0-dev.2' +release = '4.0.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/cvode/cv_intro.tex b/doc/cvode/cv_intro.tex index fcc25645fa..76a0259318 100644 --- a/doc/cvode/cv_intro.tex +++ b/doc/cvode/cv_intro.tex @@ -101,158 +101,57 @@ \section{Changes from previous versions} \subsection*{Changes in v5.0.0} -The return type of the SUNLinearSolver API function \id{SUNLinSolLastFlag} has -changed from \id{long int} to \id{sunindextype} to be consistent with the type -used to store row indices in dense and banded linear solver modules. +\subsubsection*{Build system changes} -Added Fortran 2003 interfaces to the {\nvecmanyvector}, {\nvecmpimanyvector} -and {\nvecmpiplusx}. - -Added three new utility \id{N\_Vector} functions, \id{FN\_VGetVecAtIndexVectorArray}, -\id{FN\_VSetVecAtIndexVectorArray}, and \id{FN\_VNewVectorArray}, that are for -working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. - -Added a new \id{SUNNonlinearSolver} implementation, \id{SUNNonlinsol\_PetscSNES}, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the \id{SUNNonlinSolSetConvTestFn} function in the SUNNonlinearSolver -API has been updated to take a \id{void*} data pointer as input. The supplied -data pointer will be passed to the nonlinear solver convergence test function on -each call. - -The definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in -the SUNNonlinearSolver API have been updated to remove unused input parameters. - -Fixed a bug in the {\cvode} constraint handling where the step size could be -set below the minimum step size. - -\subsection*{Changes in v5.0.0-dev.2} - -Added a new optional operation to the SUNLINEARSOLVER API, \id{SUNLinSolGetID}, -that returns a \id{SUNLinearSolver\_ID} for identifying the linear solver -module. - -Made performance improvements to the {\nveccuda} module. Users who utilize a -non-default stream should no longer see default stream synchronizations after -memory transfers. - -Added a new constructor to the {\nveccuda} module that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. - -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. - -The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have -been removed to simplify builds as SUNDIALS packages do not use BLAS directly. -For third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \id{\_LIBRARIES} variable for the third party -library e.g., \id{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. - -Added two new functions, \id{CVodeGetCurrentGamma} and \id{CVodeGetCurrentState}, -which may be useful to users who choose to provide their own nonlinear solver -implementations. - -Added a new SUNLinearSolver implementation, \id{SUNLinearSolver\_cuSolverSp\_batchQR}, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. - -Added three new accessor functions to the {\sunlinsolklu} module, -\id{SUNLinSol\_KLUGetSymbolic}, \id{SUNLinSol\_KLUGetNumeric}, and -\id{SUNLinSol\_KLUGetCommon}, to provide user access to the underlying -{\klu} solver structures. - -Fixed a bug in the {\cvode} nonlinear solver interface where the norm of the -accumulated correction was not updated when using a non-default convergence -test function. - -\subsection*{Changes in v5.0.0-dev.1} - -Several new functions were added to aid in creating custom {\nvector}, -{\sunmatrix}, {\sunlinsol}, and {\sunnonlinsol} objects. The constructors -\id{N\_VNewEmpty()}, \id{SUNMatNewEmpty()}, \id{SUNLinSolNewEmpty()}, and -\id{SUNNonlinSolNewEmpty()} allocate ``empty'' generic {\nvector}, {\sunmatrix}, -{\sunlinsol}, and {\sunnonlinsol} objects respectively with the object's content -pointer and the function pointers in the operations structure initialized to -\id{NULL}. When used in the constructor for custom objects these functions will -ease the introduction of any new optional operations to the {\nvector}, -{\sunmatrix}, {\sunlinsol}, or {\sunnonlinsol} APIs by ensuring only required -operations need to be set. Additionally, the functions \id{N\_VCopyOps(w, v)} -and \id{SUNMatCopyOps(A, B)} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the {\nvector} or {\sunmatrix} -APIs by ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. - -A new linear solver interface function \id{CVLsLinSysFn} was added as an -alternative method for evaluating the linear system $M = I - \gamma J$. - -The CVLS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \id{SUNLINEARSOLVER\_DIRECT}. - -Fixed a bug in the build system that prevented the {\nvecpthreads} module from +\begin{itemize} +\item Increased the minimum required CMake version to 3.5 for most {\sundials} +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. +% +\item The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have +been removed to simplify builds as {\sundials} packages do not use BLAS +directly. For third party libraries that require linking to BLAS, the path to +the BLAS library should be included in the \id{\_LIBRARIES} variable for the +third party library \textit{e.g.}, \id{SUPERLUDIST\_LIBRARIES} when enabling +SuperLU\_DIST. +% +\item Fixed a bug in the build system that prevented the {\nvecpthreads} module from being built. +\end{itemize} -Fixed a memory leak in the {\nvecpetsc} clone function. - -Fixed a memeory leak in {\fcvode} when not using the default nonlinear solver. - -The {\nvecmanyvector} module has been split into two versions: one -that requires MPI ({\nvecmpimanyvector}) and another that does not use -MPI at all ({\nvecmanyvector}). The associated example problems have -been similarly updated to reflect this new structure. - -An additional {\nvector} implementation, {\nvecmpiplusx}, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and {\sundials} -examples. - -The \id{*\_MPICuda} and \id{*\_MPIRaja} functions were removed from the {\nveccuda} and -{\nvecraja} implementations respectively. Accordingly, the \id{nvector\_mpicuda.h}, -\id{nvector\_mpiraja.h}, \id{libsundials\_nvecmpicuda.lib}, and~ -\id{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should use -the {\nvecmpiplusx} module coupled with {\nveccuda} or {\nvecraja} to replace the -functionality. The necessary changes are minimal and should require few code -modifications. - -The {\cvode} Fortran 2003 interface was completely redone to be more sustainable -and to allow users to write more idiomatic Fortran. The update includes new Fortran -2003 interfaces to all generic {\sundials} types (i.e. {\nvector}, {\sunmatrix}, -{\sunlinsol}, {\sunnonlinsol}), and the {\nvecp}. All existing Fortran 2003 interfaces to -{\sundials} module implementations were also redone accordingly. See Section~\ref{s:cvfort} -for more details. +\subsubsection*{NVECTOR module changes} -Removed extraneous calls to \id{N\_VMin} for simulations where -the scalar valued absolute tolerance, or all entries of the -vector-valued absolute tolerance array, are strictly positive. In -this scenario, {\cvode} will remove at least one global reduction per -time step. - - -\subsection*{Changes in v5.0.0-dev.0} - -An additional {\nvector} implementation, {\nvecmanyvector}, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see -Section \ref{ss:nvec_manyvector} for more details). This -implementation is accompanied by additions to user documentation and -{\sundials} examples. - -Eleven new optional vector operations have been added to the {\nvector} API to -support the new {\nvecmanyvector} implementation (see Chapter \ref{s:nvector} -for more details). Two of the operations, \id{N\_VGetCommunicator} and -\id{N\_VGetLength}, must be implemented by subvectors that are combined to -create an {\nvecmanyvector}, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are +\begin{itemize} +\item Two new functions were added to aid in creating custom {\nvector} objects. The +constructor \id{N\_VNewEmpty} allocates an ``empty'' generic {\nvector} with the +object's content pointer and the function pointers in the operations structure +initialized to \id{NULL}. When used in the constructor for custom objects this +function will ease the introduction of any new optional operations to the +{\nvector} API by ensuring only required operations need to be set. +Additionally, the function \id{N\_VCopyOps(w, v)} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the {\nvector} API by ensuring all operations +are copied when cloning objects. See \S\ref{ss:nvecutils} for more details. +% +\item Two new {\nvector} implementations, {\nvecmanyvector} and +{\nvecmpimanyvector}, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and {\sundials} +examples. See \S\ref{ss:nvec_manyvector} and \S\ref{ss:nvec_mpimanyvector} for +more details. +% +\item One new required vector operation and ten new optional vector operations have +been added to the {\nvector} API. The new required operation, \id{N\_VGetLength}, +returns the global length of an \id{N\_Vector}. The optional operations have +been added to support the new \newline\noindent +{\nvecmpimanyvector} implementation. The +operation \id{N\_VGetCommunicator} must be implemented by subvectors that are +combined to create an {\nvecmpimanyvector}, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are \id{N\_VDotProdLocal}, \id{N\_VMaxNormLocal}, \id{N\_VMinLocal}, @@ -260,22 +159,202 @@ \subsection*{Changes in v5.0.0-dev.0} \id{N\_VWSqrSumLocal}, \id{N\_VWSqrSumMaskLocal}, \id{N\_VInvTestLocal}, -\id{N\_VConstrMaskLocal}, and\\ +\id{N\_VConstrMaskLocal}, and \id{N\_VMinQuotientLocal}. If an {\nvector} implementation defines any of the local operations as -\id{NULL}, then the {\nvecmanyvector} will call standard {\nvector} operations -to complete the computation. +\id{NULL}, then the {\nvecmpimanyvector} will call standard {\nvector} +operations to complete the computation. See \S\ref{ss:nveclocalops} for more +details. +% +\item An additional {\nvector} implementation, {\nvecmpiplusx}, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\textit{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and {\sundials} examples. See \S\ref{ss:nvec_mpiplusx} for +more details. +% +\item The \id{*\_MPICuda} and \id{*\_MPIRaja} functions have been removed from the +{\nveccuda} and {\nvecraja} implementations respectively. Accordingly, the +\id{nvector\_mpicuda.h}, \newline\noindent +\id{nvector\_mpiraja.h}, +\id{libsundials\_nvecmpicuda.lib}, and \id{libsundials\_nvecmpicudaraja.lib} +files have been removed. Users should use the {\nvecmpiplusx} module coupled +in conjunction with the {\nveccuda} or {\nvecraja} modules to replace the +functionality. The necessary changes are minimal and should require few +code modifications. See the programs in \id{examples/ida/mpicuda} and +\id{examples/ida/mpiraja} for examples of how to use the {\nvecmpiplusx} +module with the {\nveccuda} and {\nvecraja} modules respectively. +% +\item Fixed a memory leak in the {\nvecpetsc} module clone function. +% +\item Made performance improvements to the {\nveccuda} module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. +% +\item Added a new constructor to the {\nveccuda} module that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. See \S\ref{ss:nvec_cuda_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\nvector} modules. See Chapter +\ref{s:nvector} for more details on how to use the interfaces. +% +\item Added three new {\nvector} utility functions, +\id{FN\_VGetVecAtIndexVectorArray},\newline\noindent +\id{FN\_VSetVecAtIndexVectorArray}, and +\id{FN\_VNewVectorArray}, +for working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +See \S\ref{ss:nvecutils} for more details. +\end{itemize} -A new {\sunmatrix} and {\sunlinsol} implementation was added to facilitate -the use of the {\superludist} library with SUNDIALS. +\subsubsection*{SUNMatrix module changes} -A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API. Users -who have implemented custom {\sunmatrix} modules will need to at least update -their code to set the corresponding ops structure member, \id{matvecsetup}, to \id{NULL}. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\sunmatrix} objects. The +constructor \id{SUNMatNewEmpty} allocates an ``empty'' generic {\sunmatrix} with +the object's content pointer and the function pointers in the operations +structure initialized to \id{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the {\sunmatrix} API by ensuring only required operations need to be set. +Additionally, the function \id{SUNMatCopyOps(A, B)} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the {\sunmatrix} API by ensuring all operations are +copied when cloning objects. See \S\ref{ss:sunmatrix_utilities} for more details. +% +\item A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for {\sunmatrix} implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom {\sunmatrix} modules will need to at +least update their code to set the corresponding \id{ops} structure member, +\id{matvecsetup}, to \id{NULL}. See \S\ref{ss:sunmatrix_functions} for more +details. +% +\item The generic {\sunmatrix} API now defines error codes to be returned by +{\sunmatrix} operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. See +\S\ref{ss:sunmatrix_ReturnCodes} for more details. +% +\item A new {\sunmatrix} (and {\sunlinsol}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunmat_slunrloc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunmatrix} modules. See Chapter +\ref{s:sunmatrix} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNLinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunlinsol} objects. +The constructor \id{SUNLinSolNewEmpty} allocates an ``empty'' generic +{\sunlinsol} with the object's content pointer and the function pointers +in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunlinsol} API by ensuring only required +operations need to be set. See \S\ref{ss:sunlinsol_custom} for more details. +% +\item The return type of the {\sunlinsol} API function \id{SUNLinSolLastFlag} +has changed from \id{long int} to \id{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. +% +\item Added a new optional operation to the {\sunlinsol} API, +\id{SUNLinSolGetID}, that returns a \newline\noindent +\id{SUNLinearSolver\_ID} for identifying the +linear solver module. +% +\item The {\sunlinsol} API has been updated to make the initialize and setup +functions optional. +% +\item A new {\sunlinsol} (and {\sunmatrix}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunlinsol_sludist} for more details. +% +\item Added a new {\sunlinsol} implementation, +\id{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER +sparse batched QR method for efficiently solving block diagonal linear systems +on NVIDIA GPUs. See \S\ref{ss:sunlinsol_cuspbqr} for more details. +% +\item Added three new accessor functions to the {\sunlinsolklu} module, +\id{SUNLinSol\_KLUGetSymbolic}, +\id{SUNLinSol\_KLUGetNumeric}, and +\id{SUNLinSol\_KLUGetCommon}, +to provide user access to the underlying KLU solver structures. See +\S\ref{ss:sunlinsol_klu_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunlinsol} modules. See +Chapter \ref{s:sunlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNNonlinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunnonlinsol} +objects. The constructor \id{SUNNonlinSolNewEmpty} allocates an ``empty'' +generic {\sunnonlinsol} with the object's content pointer and the function +pointers in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunnonlinsol} API by ensuring only +required operations need to be set. See \S\ref{ss:sunnonlinsol_custom} for more +details. +% +\item To facilitate the use of user supplied nonlinear solver convergence test +functions the \newline\noindent +\id{SUNNonlinSolSetConvTestFn} function in the +{\sunnonlinsol} API has been updated to take a \id{void*} data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. +% +\item The inputs values passed to the first two inputs of the \id{SUNNonlinSolSolve} +function in the {\sunnonlinsol} have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in +the {\sunnonlinsol} API have been updated to remove unused input +parameters. For more information on the nonlinear system formulation see +\S\ref{s:sunnonlinsol_interface} and for more details on the API functions see +Chapter \ref{c:sunnonlinsol}. +% +\item Added a new {\sunnonlinsol} implementation, {\sunnonlinsolpetsc}, which +interfaces to the PETSc SNES nonlinear solver API. See +\S\ref{s:sunnonlinsolpetsc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunnonlinsol} modules. See +Chapter \ref{c:sunnonlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{CVODE changes} + +\begin{itemize} +\item Fixed a bug in the {\cvode} constraint handling where the step size could be +set below the minimum step size. +% +\item Fixed a bug in the {\cvode} nonlinear solver interface where the norm of the +accumulated correction was not updated when using a non-default convergence +test function. +% +\item Fixed a memeory leak in {\fcvode} when not using the default nonlinear solver. +% +\item Removed extraneous calls to \id{N\_VMin} for simulations where the scalar valued +absolute tolerance, or all entries of the vector-valued absolute tolerance +array, are strictly positive. In this scenario, {\cvode} will remove at least +one global reduction per time step. +% +\item The CVLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type \newline\noindent +\id{SUNLINEARSOLVER\_DIRECT}. +% +\item A new linear solver interface function \id{CVLsLinSysFn} was added as an +alternative method for evaluating the linear system $M = I - \gamma J$. +% +\item Added two new functions, \id{CVodeGetCurrentGamma} and +\id{CVodeGetCurrentState}, which may be useful to users who choose to provide +their own nonlinear solver implementations. +% +\item The {\cvode} Fortran 2003 interface was completely redone to be more sustainable +and to allow users to write more idiomatic Fortran. See Chapter \ref{s:cvfort} +for more details. +\end{itemize} -The generic {\sunmatrix} API now defines error codes to be returned by {\sunmatrix} operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. \subsection*{Changes in v4.1.0} diff --git a/doc/cvodes/cvs_intro.tex b/doc/cvodes/cvs_intro.tex index 7210005938..34ac22674e 100644 --- a/doc/cvodes/cvs_intro.tex +++ b/doc/cvodes/cvs_intro.tex @@ -119,186 +119,272 @@ \section{Changes from previous versions} \subsection*{Changes in v5.0.0} -The return type of the SUNLinearSolver API function \id{SUNLinSolLastFlag} has -changed from \id{long int} to \id{sunindextype} to be consistent with the type -used to store row indices in dense and banded linear solver modules. +\subsubsection*{Build system changes} -Added Fortran 2003 interfaces to the {\nvecmanyvector}, {\nvecmpimanyvector} -and {\nvecmpiplusx}. - -Added three new utility \id{N\_Vector} functions, \id{FN\_VGetVecAtIndexVectorArray}, -\id{FN\_VSetVecAtIndexVectorArray}, and \id{FN\_VNewVectorArray}, that are for -working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. - -Created a Fortran 2003 interface to {\cvodes}. Users interested in using -{\cvodes} from Fortran should see Chapter~\ref{s:cvsfort}. - -Added a new \id{SUNNonlinearSolver} implementation, \id{SUNNonlinsol\_PetscSNES}, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the \id{SUNNonlinSolSetConvTestFn} function in the SUNNonlinearSolver -API has been updated to take a \id{void*} data pointer as input. The supplied -data pointer will be passed to the nonlinear solver convergence test function on -each call. - -The definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in -the SUNNonlinearSolver API have been updated to remove unused input parameters. - -Fixed a bug in the {\cvodes} constraint handling where the step size could be -set below the minimum step size. - -Fixed a bug in the {\cvodes} \id{cvRescale} function where the loops to compute -the array of scalars for the fused vector scale operation stopped one iteration -early. - -Fixed a bug where the \id{CVodeF} function would return the wrong flag under -certrain cirumstances. - -Fixed a bug where the \id{CVodeF} function would not return a root in -\id{CV\_NORMAL\_STEP} mode if the root occurred after the desired output time. +\begin{itemize} +\item Increased the minimum required CMake version to 3.5 for most {\sundials} +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. +% +\item The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have +been removed to simplify builds as {\sundials} packages do not use BLAS +directly. For third party libraries that require linking to BLAS, the path to +the BLAS library should be included in the \id{\_LIBRARIES} variable for the +third party library \textit{e.g.}, \id{SUPERLUDIST\_LIBRARIES} when enabling +SuperLU\_DIST. +% +\item Fixed a bug in the build system that prevented the {\nvecpthreads} module from +being built. +\end{itemize} -\subsection*{Changes in v5.0.0-dev.2} +\subsubsection*{NVECTOR module changes} -Added a new optional operation to the SUNLINEARSOLVER API, \id{SUNLinSolGetID}, -that returns a \id{SUNLinearSolver\_ID} for identifying the linear solver -module. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\nvector} objects. The +constructor \id{N\_VNewEmpty} allocates an ``empty'' generic {\nvector} with the +object's content pointer and the function pointers in the operations structure +initialized to \id{NULL}. When used in the constructor for custom objects this +function will ease the introduction of any new optional operations to the +{\nvector} API by ensuring only required operations need to be set. +Additionally, the function \id{N\_VCopyOps(w, v)} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the {\nvector} API by ensuring all operations +are copied when cloning objects. See \S\ref{ss:nvecutils} for more details. +% +\item Two new {\nvector} implementations, {\nvecmanyvector} and +{\nvecmpimanyvector}, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and {\sundials} +examples. See \S\ref{ss:nvec_manyvector} and \S\ref{ss:nvec_mpimanyvector} for +more details. +% +\item One new required vector operation and ten new optional vector operations have +been added to the {\nvector} API. The new required operation, \id{N\_VGetLength}, +returns the global length of an \id{N\_Vector}. The optional operations have +been added to support the new \newline\noindent +{\nvecmpimanyvector} implementation. The +operation \id{N\_VGetCommunicator} must be implemented by subvectors that are +combined to create an {\nvecmpimanyvector}, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are +\id{N\_VDotProdLocal}, +\id{N\_VMaxNormLocal}, +\id{N\_VMinLocal}, +\id{N\_VL1NormLocal}, +\id{N\_VWSqrSumLocal}, +\id{N\_VWSqrSumMaskLocal}, +\id{N\_VInvTestLocal}, +\id{N\_VConstrMaskLocal}, and +\id{N\_VMinQuotientLocal}. +If an {\nvector} implementation defines any of the local operations as +\id{NULL}, then the {\nvecmpimanyvector} will call standard {\nvector} +operations to complete the computation. See \S\ref{ss:nveclocalops} for more +details. +% +\item An additional {\nvector} implementation, {\nvecmpiplusx}, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\textit{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and {\sundials} examples. See \S\ref{ss:nvec_mpiplusx} for +more details. +% +\item The \id{*\_MPICuda} and \id{*\_MPIRaja} functions have been removed from the +{\nveccuda} and {\nvecraja} implementations respectively. Accordingly, the +\id{nvector\_mpicuda.h}, \newline\noindent +\id{nvector\_mpiraja.h}, +\id{libsundials\_nvecmpicuda.lib}, and \id{libsundials\_nvecmpicudaraja.lib} +files have been removed. Users should use the {\nvecmpiplusx} module coupled +in conjunction with the {\nveccuda} or {\nvecraja} modules to replace the +functionality. The necessary changes are minimal and should require few +code modifications. See the programs in \id{examples/ida/mpicuda} and +\id{examples/ida/mpiraja} for examples of how to use the {\nvecmpiplusx} +module with the {\nveccuda} and {\nvecraja} modules respectively. +% +\item Fixed a memory leak in the {\nvecpetsc} module clone function. +% +\item Made performance improvements to the {\nveccuda} module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. +% +\item Added a new constructor to the {\nveccuda} module that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. See \S\ref{ss:nvec_cuda_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\nvector} modules. See Chapter +\ref{s:nvector} for more details on how to use the interfaces. +% +\item Added three new {\nvector} utility functions, +\id{FN\_VGetVecAtIndexVectorArray},\newline\noindent +\id{FN\_VSetVecAtIndexVectorArray}, and +\id{FN\_VNewVectorArray}, +for working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +See \S\ref{ss:nvecutils} for more details. +\end{itemize} -Made performance improvements to the {\nveccuda} module. Users who utilize a -non-default stream should no longer see default stream synchronizations after -memory transfers. +\subsubsection*{SUNMatrix module changes} -Added a new constructor to the {\nveccuda} module that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\sunmatrix} objects. The +constructor \id{SUNMatNewEmpty} allocates an ``empty'' generic {\sunmatrix} with +the object's content pointer and the function pointers in the operations +structure initialized to \id{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the {\sunmatrix} API by ensuring only required operations need to be set. +Additionally, the function \id{SUNMatCopyOps(A, B)} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the {\sunmatrix} API by ensuring all operations are +copied when cloning objects. See \S\ref{ss:sunmatrix_utilities} for more details. +% +\item A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for {\sunmatrix} implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom {\sunmatrix} modules will need to at +least update their code to set the corresponding \id{ops} structure member, +\id{matvecsetup}, to \id{NULL}. See \S\ref{ss:sunmatrix_functions} for more +details. +% +\item The generic {\sunmatrix} API now defines error codes to be returned by +{\sunmatrix} operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. See +\S\ref{ss:sunmatrix_ReturnCodes} for more details. +% +\item A new {\sunmatrix} (and {\sunlinsol}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunmat_slunrloc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunmatrix} modules. See Chapter +\ref{s:sunmatrix} for more details on how to use the interfaces. +\end{itemize} -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. +\subsubsection*{SUNLinearSolver module changes} -The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have -been removed to simplify builds as SUNDIALS packages do not use BLAS directly. -For third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \id{\_LIBRARIES} variable for the third party -library e.g., \id{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. +\begin{itemize} +\item A new function was added to aid in creating custom {\sunlinsol} objects. +The constructor \id{SUNLinSolNewEmpty} allocates an ``empty'' generic +{\sunlinsol} with the object's content pointer and the function pointers +in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunlinsol} API by ensuring only required +operations need to be set. See \S\ref{ss:sunlinsol_custom} for more details. +% +\item The return type of the {\sunlinsol} API function \id{SUNLinSolLastFlag} +has changed from \id{long int} to \id{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. +% +\item Added a new optional operation to the {\sunlinsol} API, +\id{SUNLinSolGetID}, that returns a \newline\noindent +\id{SUNLinearSolver\_ID} for identifying the +linear solver module. +% +\item The {\sunlinsol} API has been updated to make the initialize and setup +functions optional. +% +\item A new {\sunlinsol} (and {\sunmatrix}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunlinsol_sludist} for more details. +% +\item Added a new {\sunlinsol} implementation, +\id{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER +sparse batched QR method for efficiently solving block diagonal linear systems +on NVIDIA GPUs. See \S\ref{ss:sunlinsol_cuspbqr} for more details. +% +\item Added three new accessor functions to the {\sunlinsolklu} module, +\id{SUNLinSol\_KLUGetSymbolic}, +\id{SUNLinSol\_KLUGetNumeric}, and +\id{SUNLinSol\_KLUGetCommon}, +to provide user access to the underlying KLU solver structures. See +\S\ref{ss:sunlinsol_klu_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunlinsol} modules. See +Chapter \ref{s:sunlinsol} for more details on how to use the interfaces. +\end{itemize} -Added new functions, \id{CVodeGetCurrentGamma}, \id{CVodeGetCurrentState}, -\id{CVodeGetCurrentStateSens}, and \id{CVodeGetCurrentSensSolveIndex} which may -be useful to users who choose to provide their own nonlinear solver -implementations. +\subsubsection*{SUNNonlinearSolver module changes} -Added a new SUNLinearSolver implementation, \id{SUNLinearSolver\_cuSolverSp\_batchQR}, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. +\begin{itemize} +\item A new function was added to aid in creating custom {\sunnonlinsol} +objects. The constructor \id{SUNNonlinSolNewEmpty} allocates an ``empty'' +generic {\sunnonlinsol} with the object's content pointer and the function +pointers in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunnonlinsol} API by ensuring only +required operations need to be set. See \S\ref{ss:sunnonlinsol_custom} for more +details. +% +\item To facilitate the use of user supplied nonlinear solver convergence test +functions the \newline\noindent +\id{SUNNonlinSolSetConvTestFn} function in the +{\sunnonlinsol} API has been updated to take a \id{void*} data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. +% +\item The inputs values passed to the first two inputs of the \id{SUNNonlinSolSolve} +function in the {\sunnonlinsol} have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in +the {\sunnonlinsol} API have been updated to remove unused input +parameters. For more information on the nonlinear system formulation see +\S\ref{s:sunnonlinsol_interface} and for more details on the API functions see +Chapter \ref{c:sunnonlinsol}. +% +\item Added a new {\sunnonlinsol} implementation, {\sunnonlinsolpetsc}, which +interfaces to the PETSc SNES nonlinear solver API. See +\S\ref{s:sunnonlinsolpetsc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunnonlinsol} modules. See +Chapter \ref{c:sunnonlinsol} for more details on how to use the interfaces. +\end{itemize} -Added three new accessor functions to the {\sunlinsolklu} module, -\id{SUNLinSol\_KLUGetSymbolic}, \id{SUNLinSol\_KLUGetNumeric}, and -\id{SUNLinSol\_KLUGetCommon}, to provide user access to the underlying -{\klu} solver structures. +\subsubsection*{CVODES changes} -Fixed a bug in the {\cvodes} nonlinear solver interface where the norm of the +\begin{itemize} +\item Fixed a bug in the {\cvodes} constraint handling where the step size could be +set below the minimum step size. +% +\item Fixed a bug in the {\cvodes} nonlinear solver interface where the norm of the accumulated correction was not updated when using a non-default convergence test function. - -\subsection*{Changes in v5.0.0-dev.1} - -Several new functions were added to aid in creating custom {\nvector}, -{\sunmatrix}, {\sunlinsol}, and {\sunnonlinsol} objects. The constructors -\id{N\_VNewEmpty()}, \id{SUNMatNewEmpty()}, \id{SUNLinSolNewEmpty()}, and -\id{SUNNonlinSolNewEmpty()} allocate ``empty'' generic {\nvector}, {\sunmatrix}, -{\sunlinsol}, and {\sunnonlinsol} objects respectively with the object's content -pointer and the function pointers in the operations structure initialized to -\id{NULL}. When used in the constructor for custom objects these functions will -ease the introduction of any new optional operations to the {\nvector}, -{\sunmatrix}, {\sunlinsol}, or {\sunnonlinsol} APIs by ensuring only required -operations need to be set. Additionally, the functions \id{N\_VCopyOps(w, v)} -and \id{SUNMatCopyOps(A, B)} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the {\nvector} or {\sunmatrix} -APIs by ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. - -A new linear solver interface function \id{CVLsLinSysFn} was added as an -alternative method for evaluating the linear system $M = I - \gamma J$. - -The CVLS interface has been updated to only zero the Jacobian matrix before +% +\item Fixed a bug in the {\cvodes} \id{cvRescale} function where the loops to compute +the array of scalars for the fused vector scale operation stopped one iteration +early. +% +\item Fixed a bug where the \id{CVodeF} function would return the wrong flag under +certrain cirumstances. +% +\item Fixed a bug where the \id{CVodeF} function would not return a root in +\id{CV\_NORMAL\_STEP} mode if the root occurred after the desired output time. +% +\item Removed extraneous calls to \id{N\_VMin} for simulations where the scalar valued +absolute tolerance, or all entries of the vector-valued absolute tolerance +array, are strictly positive. In this scenario, {\cvodes} will remove at least +one global reduction per time step. +% +\item The CVLS interface has been updated to only zero the Jacobian matrix before calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \id{SUNLINEARSOLVER\_DIRECT}. - -Fixed a bug in the build system that prevented the {\nvecpthreads} module from -being built. - -Fixed a memory leak in the {\nvecpetsc} clone function. - -The {\nvecmanyvector} module has been split into two versions: one -that requires MPI ({\nvecmpimanyvector}) and another that does not use -MPI at all ({\nvecmanyvector}). The associated example problems have -been similarly updated to reflect this new structure. - -An additional {\nvector} implementation, {\nvecmpiplusx}, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and {\sundials} -examples. - -The \id{*\_MPICuda} and \id{*\_MPIRaja} functions were removed from the {\nveccuda} and -{\nvecraja} implementations respectively. Accordingly, the \id{nvector\_mpicuda.h}, -\id{nvector\_mpiraja.h}, \id{libsundials\_nvecmpicuda.lib}, and~ -\id{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should use -the {\nvecmpiplusx} module coupled with {\nveccuda} or {\nvecraja} to replace the -functionality. The necessary changes are minimal and should require few code -modifications. - -Removed extraneous calls to \id{N\_VMin} for simulations where -the scalar valued absolute tolerance, or all entries of the -vector-valued absolute tolerance array, are strictly positive. In -this scenario, {\cvodes} will remove at least one global reduction per -time step. - - -\subsection*{Changes in v5.0.0-dev.0} - -An additional {\nvector} implementation, {\nvecmanyvector}, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see -Section \ref{ss:nvec_manyvector} for more details). This -implementation is accompanied by additions to user documentation and -{\sundials} examples. - -Eleven new optional vector operations have been added to the {\nvector} API to -support the new {\nvecmanyvector} implementation (see Chapter \ref{s:nvector} -for more details). Two of the operations, \id{N\_VGetCommunicator} and -\id{N\_VGetLength}, must be implemented by subvectors that are combined to -create an {\nvecmanyvector}, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are -\id{N\_VDotProdLocal}, -\id{N\_VMaxNormLocal}, -\id{N\_VMinLocal}, -\id{N\_VL1NormLocal}, -\id{N\_VWSqrSumLocal}, -\id{N\_VWSqrSumMaskLocal}, -\id{N\_VInvTestLocal}, -\id{N\_VConstrMaskLocal}, and\\ -\id{N\_VMinQuotientLocal}. -If an {\nvector} implementation defines any of the local operations as -\id{NULL}, then the {\nvecmanyvector} will call standard {\nvector} operations -to complete the computation. - -A new {\sunmatrix} and {\sunlinsol} implementation was added to facilitate -the use of the {\superludist} library with SUNDIALS. +solver has type \newline\noindent +\id{SUNLINEARSOLVER\_DIRECT}. +% +\item A new linear solver interface function \id{CVLsLinSysFn} was added as an +alternative method for evaluating the linear system $M = I - \gamma J$. +% +\item Added new functions, +\id{CVodeGetCurrentGamma}, +\id{CVodeGetCurrentState}, \newline\noindent +\id{CVodeGetCurrentStateSens}, and +\id{CVodeGetCurrentSensSolveIndex} +which may be useful to users who choose to provide their own nonlinear solver +implementations. +% +\item Added a Fortran 2003 interface to {\cvodes}. See Chapter~\ref{s:cvsfort} +for more details. +\end{itemize} -A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API. Users -who have implemented custom {\sunmatrix} modules will need to at least update -their code to set the corresponding ops structure member, \id{matvecsetup}, to \id{NULL}. -The generic {\sunmatrix} API now defines error codes to be returned by {\sunmatrix} operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. \subsection*{Changes in v4.1.0} diff --git a/doc/ida/ida_intro.tex b/doc/ida/ida_intro.tex index 9a039347db..6f0b9d5f76 100644 --- a/doc/ida/ida_intro.tex +++ b/doc/ida/ida_intro.tex @@ -68,145 +68,57 @@ \section{Changes from previous versions} \subsection*{Changes in v5.0.0} -The return type of the SUNLinearSolver API function \id{SUNLinSolLastFlag} has -changed from \id{long int} to \id{sunindextype} to be consistent with the type -used to store row indices in dense and banded linear solver modules. +\subsubsection*{Build system changes} -Added Fortran 2003 interfaces to the {\nvecmanyvector}, {\nvecmpimanyvector} -and {\nvecmpiplusx}. - -Added three new utility \id{N\_Vector} functions, \id{FN\_VGetVecAtIndexVectorArray}, -\id{FN\_VSetVecAtIndexVectorArray}, and \id{FN\_VNewVectorArray}, that are for -working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. - -Added a new \id{SUNNonlinearSolver} implementation, \id{SUNNonlinsol\_PetscSNES}, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the \id{SUNNonlinSolSetConvTestFn} function in the SUNNonlinearSolver -API has been updated to take a \id{void*} data pointer as input. The supplied -data pointer will be passed to the nonlinear solver convergence test function on -each call. - -The definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in -the SUNNonlinearSolver API have been updated to remove unused input parameters. - -\subsection*{Changes in v5.0.0-dev.2} - -Added a new optional operation to the SUNLINEARSOLVER API, \id{SUNLinSolGetID}, -that returns a \id{SUNLinearSolver\_ID} for identifying the linear solver -module. - -Made performance improvements to the {\nveccuda} module. Users who utilize a -non-default stream should no longer see default stream synchronizations after -memory transfers. - -Added a new constructor to the {\nveccuda} module that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. - -Added a new SUNLinearSolver implementation, \id{SUNLinearSolver\_cuSolverSp\_batchQR}, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. - -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. - -The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have -been removed to simplify builds as SUNDIALS packages do not use BLAS directly. -For third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \id{\_LIBRARIES} variable for the third party -library e.g., \id{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. - -Added three new accessor functions to the {\sunlinsolklu} module, -\id{SUNLinSol\_KLUGetSymbolic}, \id{SUNLinSol\_KLUGetNumeric}, and -\id{SUNLinSol\_KLUGetCommon}, to provide user access to the underlying -{\klu} solver structures. - -A bug was fixed in the IDA linear solver interface where an incorrect -Jacobian-vector product increment was used with iterative solvers other than -SPGMR and SPFGMR. - -\subsection*{Changes in v5.0.0-dev.1} - -Several new functions were added to aid in creating custom {\nvector}, -{\sunmatrix}, {\sunlinsol}, and {\sunnonlinsol} objects. The constructors -\id{N\_VNewEmpty()}, \id{SUNMatNewEmpty()}, \id{SUNLinSolNewEmpty()}, and -\id{SUNNonlinSolNewEmpty()} allocate ``empty'' generic {\nvector}, {\sunmatrix}, -{\sunlinsol}, and {\sunnonlinsol} objects respectively with the object's content -pointer and the function pointers in the operations structure initialized to -\id{NULL}. When used in the constructor for custom objects these functions will -ease the introduction of any new optional operations to the {\nvector}, -{\sunmatrix}, {\sunlinsol}, or {\sunnonlinsol} APIs by ensuring only required -operations need to be set. Additionally, the functions \id{N\_VCopyOps(w, v)} -and \id{SUNMatCopyOps(A, B)} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the {\nvector} or {\sunmatrix} -APIs by ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. - -The IDALS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \id{SUNLINEARSOLVER\_DIRECT}. - -Fixed a bug in the build system that prevented the {\nvecpthreads} module from +\begin{itemize} +\item Increased the minimum required CMake version to 3.5 for most {\sundials} +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. +% +\item The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have +been removed to simplify builds as {\sundials} packages do not use BLAS +directly. For third party libraries that require linking to BLAS, the path to +the BLAS library should be included in the \id{\_LIBRARIES} variable for the +third party library \textit{e.g.}, \id{SUPERLUDIST\_LIBRARIES} when enabling +SuperLU\_DIST. +% +\item Fixed a bug in the build system that prevented the {\nvecpthreads} module from being built. +\end{itemize} + +\subsubsection*{NVECTOR module changes} -Fixed a memory leak in the {\nvecpetsc} clone function. - -Fixed a memeory leak in {\fida} when not using the default nonlinear solver. - -The {\nvecmanyvector} module has been split into two versions: one -that requires MPI ({\nvecmpimanyvector}) and another that does not use -MPI at all ({\nvecmanyvector}). The associated example problems have -been similarly updated to reflect this new structure. - -An additional {\nvector} implementation, {\nvecmpiplusx}, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and {\sundials} -examples. - -The \id{*\_MPICuda} and \id{*\_MPIRaja} functions were removed from the {\nveccuda} and -{\nvecraja} implementations respectively. Accordingly, the \id{nvector\_mpicuda.h}, -\id{nvector\_mpiraja.h}, \id{libsundials\_nvecmpicuda.lib}, and~ -\id{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should use -the {\nvecmpiplusx} module coupled with {\nveccuda} or {\nvecraja} to replace the -functionality. The necessary changes are minimal and should require few code -modifications. - -A new Fortran 2003 interface to {\ida} was added. This includes Fortran 2003 interfaces -to all generic {\sundials} types (i.e. {\nvector}, {\sunmatrix}, {\sunlinsol}, {\sunnonlinsol}), -and many of the module implementations. See Section~\ref{s:idafort} for more details. - -Removed extraneous calls to \id{N\_VMin} for simulations where -the scalar valued absolute tolerance, or all entries of the -vector-valued absolute tolerance array, are strictly positive. In -this scenario, {\ida} will remove at least one global reduction per -time step. - - -\subsection*{Changes in v5.0.0-dev.0} - -An additional {\nvector} implementation, {\nvecmanyvector}, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see -Section \ref{ss:nvec_manyvector} for more details). This -implementation is accompanied by additions to user documentation and -{\sundials} examples. - -Eleven new optional vector operations have been added to the {\nvector} API to -support the new {\nvecmanyvector} implementation (see Chapter \ref{s:nvector} -for more details). Two of the operations, \id{N\_VGetCommunicator} and -\id{N\_VGetLength}, must be implemented by subvectors that are combined to -create an {\nvecmanyvector}, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are +\begin{itemize} +\item Two new functions were added to aid in creating custom {\nvector} objects. The +constructor \id{N\_VNewEmpty} allocates an ``empty'' generic {\nvector} with the +object's content pointer and the function pointers in the operations structure +initialized to \id{NULL}. When used in the constructor for custom objects this +function will ease the introduction of any new optional operations to the +{\nvector} API by ensuring only required operations need to be set. +Additionally, the function \id{N\_VCopyOps(w, v)} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the {\nvector} API by ensuring all operations +are copied when cloning objects. See \S\ref{ss:nvecutils} for more details. +% +\item Two new {\nvector} implementations, {\nvecmanyvector} and +{\nvecmpimanyvector}, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and {\sundials} +examples. See \S\ref{ss:nvec_manyvector} and \S\ref{ss:nvec_mpimanyvector} for +more details. +% +\item One new required vector operation and ten new optional vector operations have +been added to the {\nvector} API. The new required operation, \id{N\_VGetLength}, +returns the global length of an \id{N\_Vector}. The optional operations have +been added to support the new \newline\noindent +{\nvecmpimanyvector} implementation. The +operation \id{N\_VGetCommunicator} must be implemented by subvectors that are +combined to create an {\nvecmpimanyvector}, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are \id{N\_VDotProdLocal}, \id{N\_VMaxNormLocal}, \id{N\_VMinLocal}, @@ -214,22 +126,202 @@ \subsection*{Changes in v5.0.0-dev.0} \id{N\_VWSqrSumLocal}, \id{N\_VWSqrSumMaskLocal}, \id{N\_VInvTestLocal}, -\id{N\_VConstrMaskLocal}, and\\ +\id{N\_VConstrMaskLocal}, and \id{N\_VMinQuotientLocal}. If an {\nvector} implementation defines any of the local operations as -\id{NULL}, then the {\nvecmanyvector} will call standard {\nvector} operations -to complete the computation. +\id{NULL}, then the {\nvecmpimanyvector} will call standard {\nvector} +operations to complete the computation. See \S\ref{ss:nveclocalops} for more +details. +% +\item An additional {\nvector} implementation, {\nvecmpiplusx}, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\textit{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and {\sundials} examples. See \S\ref{ss:nvec_mpiplusx} for +more details. +% +\item The \id{*\_MPICuda} and \id{*\_MPIRaja} functions have been removed from the +{\nveccuda} and {\nvecraja} implementations respectively. Accordingly, the +\id{nvector\_mpicuda.h}, \newline\noindent +\id{nvector\_mpiraja.h}, +\id{libsundials\_nvecmpicuda.lib}, and \id{libsundials\_nvecmpicudaraja.lib} +files have been removed. Users should use the {\nvecmpiplusx} module coupled +in conjunction with the {\nveccuda} or {\nvecraja} modules to replace the +functionality. The necessary changes are minimal and should require few +code modifications. See the programs in \id{examples/ida/mpicuda} and +\id{examples/ida/mpiraja} for examples of how to use the {\nvecmpiplusx} +module with the {\nveccuda} and {\nvecraja} modules respectively. +% +\item Fixed a memory leak in the {\nvecpetsc} module clone function. +% +\item Made performance improvements to the {\nveccuda} module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. +% +\item Added a new constructor to the {\nveccuda} module that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. See \S\ref{ss:nvec_cuda_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\nvector} modules. See Chapter +\ref{s:nvector} for more details on how to use the interfaces. +% +\item Added three new {\nvector} utility functions, +\id{FN\_VGetVecAtIndexVectorArray},\newline\noindent +\id{FN\_VSetVecAtIndexVectorArray}, and +\id{FN\_VNewVectorArray}, +for working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +See \S\ref{ss:nvecutils} for more details. +\end{itemize} + +\subsubsection*{SUNMatrix module changes} -A new {\sunmatrix} and {\sunlinsol} implementation was added to facilitate -the use of the {\superludist} library with SUNDIALS. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\sunmatrix} objects. The +constructor \id{SUNMatNewEmpty} allocates an ``empty'' generic {\sunmatrix} with +the object's content pointer and the function pointers in the operations +structure initialized to \id{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the {\sunmatrix} API by ensuring only required operations need to be set. +Additionally, the function \id{SUNMatCopyOps(A, B)} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the {\sunmatrix} API by ensuring all operations are +copied when cloning objects. See \S\ref{ss:sunmatrix_utilities} for more details. +% +\item A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for {\sunmatrix} implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom {\sunmatrix} modules will need to at +least update their code to set the corresponding \id{ops} structure member, +\id{matvecsetup}, to \id{NULL}. See \S\ref{ss:sunmatrix_functions} for more +details. +% +\item The generic {\sunmatrix} API now defines error codes to be returned by +{\sunmatrix} operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. See +\S\ref{ss:sunmatrix_ReturnCodes} for more details. +% +\item A new {\sunmatrix} (and {\sunlinsol}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunmat_slunrloc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunmatrix} modules. See Chapter +\ref{s:sunmatrix} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNLinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunlinsol} objects. +The constructor \id{SUNLinSolNewEmpty} allocates an ``empty'' generic +{\sunlinsol} with the object's content pointer and the function pointers +in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunlinsol} API by ensuring only required +operations need to be set. See \S\ref{ss:sunlinsol_custom} for more details. +% +\item The return type of the {\sunlinsol} API function \id{SUNLinSolLastFlag} +has changed from \id{long int} to \id{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. +% +\item Added a new optional operation to the {\sunlinsol} API, +\id{SUNLinSolGetID}, that returns a \newline\noindent +\id{SUNLinearSolver\_ID} for identifying the +linear solver module. +% +\item The {\sunlinsol} API has been updated to make the initialize and setup +functions optional. +% +\item A new {\sunlinsol} (and {\sunmatrix}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunlinsol_sludist} for more details. +% +\item Added a new {\sunlinsol} implementation, +\id{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER +sparse batched QR method for efficiently solving block diagonal linear systems +on NVIDIA GPUs. See \S\ref{ss:sunlinsol_cuspbqr} for more details. +% +\item Added three new accessor functions to the {\sunlinsolklu} module, +\id{SUNLinSol\_KLUGetSymbolic}, +\id{SUNLinSol\_KLUGetNumeric}, and +\id{SUNLinSol\_KLUGetCommon}, +to provide user access to the underlying KLU solver structures. See +\S\ref{ss:sunlinsol_klu_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunlinsol} modules. See +Chapter \ref{s:sunlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNNonlinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunnonlinsol} +objects. The constructor \id{SUNNonlinSolNewEmpty} allocates an ``empty'' +generic {\sunnonlinsol} with the object's content pointer and the function +pointers in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunnonlinsol} API by ensuring only +required operations need to be set. See \S\ref{ss:sunnonlinsol_custom} for more +details. +% +\item To facilitate the use of user supplied nonlinear solver convergence test +functions the \newline\noindent +\id{SUNNonlinSolSetConvTestFn} function in the +{\sunnonlinsol} API has been updated to take a \id{void*} data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. +% +\item The inputs values passed to the first two inputs of the \id{SUNNonlinSolSolve} +function in the {\sunnonlinsol} have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in +the {\sunnonlinsol} API have been updated to remove unused input +parameters. For more information on the nonlinear system formulation see +\S\ref{s:sunnonlinsol_interface} and for more details on the API functions see +Chapter \ref{c:sunnonlinsol}. +% +\item Added a new {\sunnonlinsol} implementation, {\sunnonlinsolpetsc}, which +interfaces to the PETSc SNES nonlinear solver API. See +\S\ref{s:sunnonlinsolpetsc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunnonlinsol} modules. See +Chapter \ref{c:sunnonlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{IDA changes} + +\begin{itemize} +\item A bug was fixed in the {\ida} linear solver interface where an incorrect +Jacobian-vector product increment was used with iterative solvers other than +{\sunlinsolspgmr} and {\sunlinsolspfgmr}. +% +\item Fixed a memeory leak in {\fida} when not using the default nonlinear +solver. +% +\item Removed extraneous calls to \id{N\_VMin} for simulations where the scalar +valued absolute tolerance, or all entries of the vector-valued absolute +tolerance array, are strictly positive. In this scenario, {\ida} will remove at +least one global reduction per time step. +% +\item The IDALS interface has been updated to only zero the Jacobian matrix +before calling a user-supplied Jacobian evaluation function when the attached +linear solver has type \newline\noindent +\id{SUNLINEARSOLVER\_DIRECT}. +% +\item Added the new functions, +\id{IDAGetCurentCj}, +\id{IDAGetCurrentY}, +\id{IDAGetCurrentYp}, \newline\noindent +\id{IDAComputeCurrentY}, and +\id{IDAComputeCurrentYp} +which may be useful to users who choose to provide their own nonlinear solver +implementations. +% +\item Added a Fortran 2003 interface to {\ida}. See Chapter~\ref{s:idafort} for +more details. +\end{itemize} -A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API. Users -who have implemented custom {\sunmatrix} modules will need to at least update -their code to set the corresponding ops structure member, \id{matvecsetup}, to \id{NULL}. -The generic {\sunmatrix} API now defines error codes to be returned by {\sunmatrix} operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. \subsection*{Changes in v4.1.0} diff --git a/doc/idas/idas_intro.tex b/doc/idas/idas_intro.tex index 12e23f28ad..f430f92a88 100644 --- a/doc/idas/idas_intro.tex +++ b/doc/idas/idas_intro.tex @@ -89,150 +89,57 @@ \section{Changes from previous versions} \subsection*{Changes in v4.0.0} -The return type of the SUNLinearSolver API function \id{SUNLinSolLastFlag} has -changed from \id{long int} to \id{sunindextype} to be consistent with the type -used to store row indices in dense and banded linear solver modules. +\subsubsection*{Build system changes} -Added Fortran 2003 interfaces to the {\nvecmanyvector}, {\nvecmpimanyvector} -and {\nvecmpiplusx}. - -Added three new utility \id{N\_Vector} functions, \id{FN\_VGetVecAtIndexVectorArray}, -\id{FN\_VSetVecAtIndexVectorArray}, and \id{FN\_VNewVectorArray}, that are for -working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. - -Created a Fortran 2003 interface to {\idas}. Users interested in using -{\idas} from Fortran should see Chapter~\ref{s:idasfort}. - -Added a new \id{SUNNonlinearSolver} implementation, \id{SUNNonlinsol\_PetscSNES}, -which interfaces to the PETSc SNES nonlinear solver API. - -To facilitate the use of user supplied nonlinear solver convergence test -functions the \id{SUNNonlinSolSetConvTestFn} function in the SUNNonlinearSolver -API has been updated to take a \id{void*} data pointer as input. The supplied -data pointer will be passed to the nonlinear solver convergence test function on -each call. - -The definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in -the SUNNonlinearSolver API have been updated to remove unused input parameters. - -Fixed a bug where the \id{IDASolveF} function would return the wrong flag under -certrain cirumstances. - -Fixed a bug where the \id{IDASolveF} function would not return a root in -\id{IDA\_NORMAL\_STEP} mode if the root occurred after the desired output time. - -\subsection*{Changes in v4.0.0-dev.2} - -Added a new optional operation to the SUNLINEARSOLVER API, \id{SUNLinSolGetID}, -that returns a \id{SUNLinearSolver\_ID} for identifying the linear solver -module. - -Made performance improvements to the {\nveccuda} module. Users who utilize a -non-default stream should no longer see default stream synchronizations after -memory transfers. - -Added a new constructor to the {\nveccuda} module that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. - -Added a new SUNLinearSolver implementation, \id{SUNLinearSolver\_cuSolverSp\_batchQR}, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. - -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. - -The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have -been removed to simplify builds as SUNDIALS packages do not use BLAS directly. -For third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \id{\_LIBRARIES} variable for the third party -library e.g., \id{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. - -Added three new accessor functions to the {\sunlinsolklu} module, -\id{SUNLinSol\_KLUGetSymbolic}, \id{SUNLinSol\_KLUGetNumeric}, and -\id{SUNLinSol\_KLUGetCommon}, to provide user access to the underlying -{\klu} solver structures. - -A bug was fixed in the IDAS linear solver interface where an incorrect -Jacobian-vector product increment was used with iterative solvers other than -SPGMR and SPFGMR. - -\subsection*{Changes in v4.0.0-dev.1} - -Several new functions were added to aid in creating custom {\nvector}, -{\sunmatrix}, {\sunlinsol}, and {\sunnonlinsol} objects. The constructors -\id{N\_VNewEmpty()}, \id{SUNMatNewEmpty()}, \id{SUNLinSolNewEmpty()}, and -\id{SUNNonlinSolNewEmpty()} allocate ``empty'' generic {\nvector}, {\sunmatrix}, -{\sunlinsol}, and {\sunnonlinsol} objects respectively with the object's content -pointer and the function pointers in the operations structure initialized to -\id{NULL}. When used in the constructor for custom objects these functions will -ease the introduction of any new optional operations to the {\nvector}, -{\sunmatrix}, {\sunlinsol}, or {\sunnonlinsol} APIs by ensuring only required -operations need to be set. Additionally, the functions \id{N\_VCopyOps(w, v)} -and \id{SUNMatCopyOps(A, B)} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the {\nvector} or {\sunmatrix} -APIs by ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup -functions optional. - -The IDALS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \id{SUNLINEARSOLVER\_DIRECT}. - -Fixed a bug in the build system that prevented the {\nvecpthreads} module from +\begin{itemize} +\item Increased the minimum required CMake version to 3.5 for most {\sundials} +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. +% +\item The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have +been removed to simplify builds as {\sundials} packages do not use BLAS +directly. For third party libraries that require linking to BLAS, the path to +the BLAS library should be included in the \id{\_LIBRARIES} variable for the +third party library \textit{e.g.}, \id{SUPERLUDIST\_LIBRARIES} when enabling +SuperLU\_DIST. +% +\item Fixed a bug in the build system that prevented the {\nvecpthreads} module from being built. +\end{itemize} -Fixed a memory leak in the {\nvecpetsc} clone function. - -Fixed a bug in \id{IDAQuadReInitB} where an incorrect memory structure was -passed to \id{IDAQuadReInit}. +\subsubsection*{NVECTOR module changes} -The {\nvecmanyvector} module has been split into two versions: one -that requires MPI ({\nvecmpimanyvector}) and another that does not use -MPI at all ({\nvecmanyvector}). The associated example problems have -been similarly updated to reflect this new structure. - -An additional {\nvector} implementation, {\nvecmpiplusx}, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and {\sundials} -examples. - -The \id{*\_MPICuda} and \id{*\_MPIRaja} functions were removed from the {\nveccuda} and -{\nvecraja} implementations respectively. Accordingly, the \id{nvector\_mpicuda.h}, -\id{nvector\_mpiraja.h}, \id{libsundials\_nvecmpicuda.lib}, and~ -\id{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should use -the {\nvecmpiplusx} module coupled with {\nveccuda} or {\nvecraja} to replace the -functionality. The necessary changes are minimal and should require few code -modifications. - -Removed extraneous calls to \id{N\_VMin} for simulations where -the scalar valued absolute tolerance, or all entries of the -vector-valued absolute tolerance array, are strictly positive. In -this scenario, {\idas} will remove at least one global reduction per -time step. - - -\subsection*{Changes in v4.0.0-dev.0} - -An additional {\nvector} implementation, {\nvecmanyvector}, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see -Section \ref{ss:nvec_manyvector} for more details). This -implementation is accompanied by additions to user documentation and -{\sundials} examples. - -Eleven new optional vector operations have been added to the {\nvector} API to -support the new {\nvecmanyvector} implementation (see Chapter \ref{s:nvector} -for more details). Two of the operations, \id{N\_VGetCommunicator} and -\id{N\_VGetLength}, must be implemented by subvectors that are combined to -create an {\nvecmanyvector}, but are not used outside of this context. The -remaining nine operations are optional local reduction operations intended to -eliminate unnecessary latency when performing vector reduction operations -(norms, etc.) on distributed memory systems. The optional local reduction vector -operations are +\begin{itemize} +\item Two new functions were added to aid in creating custom {\nvector} objects. The +constructor \id{N\_VNewEmpty} allocates an ``empty'' generic {\nvector} with the +object's content pointer and the function pointers in the operations structure +initialized to \id{NULL}. When used in the constructor for custom objects this +function will ease the introduction of any new optional operations to the +{\nvector} API by ensuring only required operations need to be set. +Additionally, the function \id{N\_VCopyOps(w, v)} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the {\nvector} API by ensuring all operations +are copied when cloning objects. See \S\ref{ss:nvecutils} for more details. +% +\item Two new {\nvector} implementations, {\nvecmanyvector} and +{\nvecmpimanyvector}, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and {\sundials} +examples. See \S\ref{ss:nvec_manyvector} and \S\ref{ss:nvec_mpimanyvector} for +more details. +% +\item One new required vector operation and ten new optional vector operations have +been added to the {\nvector} API. The new required operation, \id{N\_VGetLength}, +returns the global length of an \id{N\_Vector}. The optional operations have +been added to support the new \newline\noindent +{\nvecmpimanyvector} implementation. The +operation \id{N\_VGetCommunicator} must be implemented by subvectors that are +combined to create an {\nvecmpimanyvector}, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are \id{N\_VDotProdLocal}, \id{N\_VMaxNormLocal}, \id{N\_VMinLocal}, @@ -240,22 +147,211 @@ \subsection*{Changes in v4.0.0-dev.0} \id{N\_VWSqrSumLocal}, \id{N\_VWSqrSumMaskLocal}, \id{N\_VInvTestLocal}, -\id{N\_VConstrMaskLocal}, and\\ +\id{N\_VConstrMaskLocal}, and \id{N\_VMinQuotientLocal}. If an {\nvector} implementation defines any of the local operations as -\id{NULL}, then the {\nvecmanyvector} will call standard {\nvector} operations -to complete the computation. +\id{NULL}, then the {\nvecmpimanyvector} will call standard {\nvector} +operations to complete the computation. See \S\ref{ss:nveclocalops} for more +details. +% +\item An additional {\nvector} implementation, {\nvecmpiplusx}, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\textit{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and {\sundials} examples. See \S\ref{ss:nvec_mpiplusx} for +more details. +% +\item The \id{*\_MPICuda} and \id{*\_MPIRaja} functions have been removed from the +{\nveccuda} and {\nvecraja} implementations respectively. Accordingly, the +\id{nvector\_mpicuda.h}, \newline\noindent +\id{nvector\_mpiraja.h}, +\id{libsundials\_nvecmpicuda.lib}, and \id{libsundials\_nvecmpicudaraja.lib} +files have been removed. Users should use the {\nvecmpiplusx} module coupled +in conjunction with the {\nveccuda} or {\nvecraja} modules to replace the +functionality. The necessary changes are minimal and should require few +code modifications. See the programs in \id{examples/ida/mpicuda} and +\id{examples/ida/mpiraja} for examples of how to use the {\nvecmpiplusx} +module with the {\nveccuda} and {\nvecraja} modules respectively. +% +\item Fixed a memory leak in the {\nvecpetsc} module clone function. +% +\item Made performance improvements to the {\nveccuda} module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. +% +\item Added a new constructor to the {\nveccuda} module that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. See \S\ref{ss:nvec_cuda_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\nvector} modules. See Chapter +\ref{s:nvector} for more details on how to use the interfaces. +% +\item Added three new {\nvector} utility functions, +\id{FN\_VGetVecAtIndexVectorArray},\newline\noindent +\id{FN\_VSetVecAtIndexVectorArray}, and +\id{FN\_VNewVectorArray}, +for working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +See \S\ref{ss:nvecutils} for more details. +\end{itemize} -A new {\sunmatrix} and {\sunlinsol} implementation was added to facilitate -the use of the {\superludist} library with SUNDIALS. +\subsubsection*{SUNMatrix module changes} -A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API. Users -who have implemented custom {\sunmatrix} modules will need to at least update -their code to set the corresponding ops structure member, \id{matvecsetup}, to \id{NULL}. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\sunmatrix} objects. The +constructor \id{SUNMatNewEmpty} allocates an ``empty'' generic {\sunmatrix} with +the object's content pointer and the function pointers in the operations +structure initialized to \id{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the {\sunmatrix} API by ensuring only required operations need to be set. +Additionally, the function \id{SUNMatCopyOps(A, B)} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the {\sunmatrix} API by ensuring all operations are +copied when cloning objects. See \S\ref{ss:sunmatrix_utilities} for more details. +% +\item A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for {\sunmatrix} implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom {\sunmatrix} modules will need to at +least update their code to set the corresponding \id{ops} structure member, +\id{matvecsetup}, to \id{NULL}. See \S\ref{ss:sunmatrix_functions} for more +details. +% +\item The generic {\sunmatrix} API now defines error codes to be returned by +{\sunmatrix} operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. See +\S\ref{ss:sunmatrix_ReturnCodes} for more details. +% +\item A new {\sunmatrix} (and {\sunlinsol}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunmat_slunrloc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunmatrix} modules. See Chapter +\ref{s:sunmatrix} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNLinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunlinsol} objects. +The constructor \id{SUNLinSolNewEmpty} allocates an ``empty'' generic +{\sunlinsol} with the object's content pointer and the function pointers +in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunlinsol} API by ensuring only required +operations need to be set. See \S\ref{ss:sunlinsol_custom} for more details. +% +\item The return type of the {\sunlinsol} API function \id{SUNLinSolLastFlag} +has changed from \id{long int} to \id{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. +% +\item Added a new optional operation to the {\sunlinsol} API, +\id{SUNLinSolGetID}, that returns a \newline\noindent +\id{SUNLinearSolver\_ID} for identifying the +linear solver module. +% +\item The {\sunlinsol} API has been updated to make the initialize and setup +functions optional. +% +\item A new {\sunlinsol} (and {\sunmatrix}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunlinsol_sludist} for more details. +% +\item Added a new {\sunlinsol} implementation, +\id{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER +sparse batched QR method for efficiently solving block diagonal linear systems +on NVIDIA GPUs. See \S\ref{ss:sunlinsol_cuspbqr} for more details. +% +\item Added three new accessor functions to the {\sunlinsolklu} module, +\id{SUNLinSol\_KLUGetSymbolic}, +\id{SUNLinSol\_KLUGetNumeric}, and +\id{SUNLinSol\_KLUGetCommon}, +to provide user access to the underlying KLU solver structures. See +\S\ref{ss:sunlinsol_klu_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunlinsol} modules. See +Chapter \ref{s:sunlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{SUNNonlinearSolver module changes} + +\begin{itemize} +\item A new function was added to aid in creating custom {\sunnonlinsol} +objects. The constructor \id{SUNNonlinSolNewEmpty} allocates an ``empty'' +generic {\sunnonlinsol} with the object's content pointer and the function +pointers in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunnonlinsol} API by ensuring only +required operations need to be set. See \S\ref{ss:sunnonlinsol_custom} for more +details. +% +\item To facilitate the use of user supplied nonlinear solver convergence test +functions the \newline\noindent +\id{SUNNonlinSolSetConvTestFn} function in the +{\sunnonlinsol} API has been updated to take a \id{void*} data pointer as +input. The supplied data pointer will be passed to the nonlinear solver +convergence test function on each call. +% +\item The inputs values passed to the first two inputs of the \id{SUNNonlinSolSolve} +function in the {\sunnonlinsol} have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of \id{SUNNonlinSolLSetupFn} and \id{SUNNonlinSolLSolveFn} in +the {\sunnonlinsol} API have been updated to remove unused input +parameters. For more information on the nonlinear system formulation see +\S\ref{s:sunnonlinsol_interface} and for more details on the API functions see +Chapter \ref{c:sunnonlinsol}. +% +\item Added a new {\sunnonlinsol} implementation, {\sunnonlinsolpetsc}, which +interfaces to the PETSc SNES nonlinear solver API. See +\S\ref{s:sunnonlinsolpetsc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunnonlinsol} modules. See +Chapter \ref{c:sunnonlinsol} for more details on how to use the interfaces. +\end{itemize} + +\subsubsection*{IDAS changes} + +\begin{itemize} +\item A bug was fixed in the {\idas} linear solver interface where an incorrect +Jacobian-vector product increment was used with iterative solvers other than +{\sunlinsolspgmr} and {\sunlinsolspfgmr}. +% +\item Fixed a bug where the \id{IDASolveF} function would not return a root in +\id{IDA\_NORMAL\_STEP} mode if the root occurred after the desired output time. +% +\item Fixed a bug where the \id{IDASolveF} function would return the wrong flag +under certrain cirumstances. +% +\item Fixed a bug in \id{IDAQuadReInitB} where an incorrect memory structure was +passed to \id{IDAQuadReInit}. +% +\item Removed extraneous calls to \id{N\_VMin} for simulations where the scalar +valued absolute tolerance, or all entries of the vector-valued absolute +tolerance array, are strictly positive. In this scenario, {\idas} will remove at +least one global reduction per time step. +% +\item The IDALS interface has been updated to only zero the Jacobian matrix +before calling a user-supplied Jacobian evaluation function when the attached +linear solver has type \newline\noindent +\id{SUNLINEARSOLVER\_DIRECT}. +% +\item Added the new functions, +\id{IDAGetCurentCj}, +\id{IDAGetCurrentY}, +\id{IDAGetCurrentYp}, \newline\noindent +\id{IDAComputeCurrentY}, +\id{IDAComputeCurrentYp}, +\id{IDAGetCurrentYSens}, +\id{IDAGetCurrentYpSens}, +\id{IDAComputeCurrentYSens}, +and \id{IDAComputeCurrentYpSens}, +which may be useful to users who choose to provide their own nonlinear solver +implementations. +% +\item Added a Fortran 2003 interface to {\idas}. See Chapter~\ref{s:idasfort} for +more details. +\end{itemize} -The generic {\sunmatrix} API now defines error codes to be returned by {\sunmatrix} operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. \subsection*{Changes in v3.1.0} diff --git a/doc/kinsol/kin_intro.tex b/doc/kinsol/kin_intro.tex index f540fefff1..0868159570 100644 --- a/doc/kinsol/kin_intro.tex +++ b/doc/kinsol/kin_intro.tex @@ -111,105 +111,205 @@ \section{Changes from previous versions} \subsection*{Changes in v5.0.0} -The return type of the SUNLinearSolver API function \id{SUNLinSolLastFlag} has -changed from \id{long int} to \id{sunindextype} to be consistent with the type -used to store row indices in dense and banded linear solver modules. +\subsubsection*{Build system changes} -Added Fortran 2003 interfaces to the {\nvecmanyvector}, {\nvecmpimanyvector} -and {\nvecmpiplusx}. +\begin{itemize} +\item Increased the minimum required CMake version to 3.5 for most {\sundials} +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. +% +\item The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have +been removed to simplify builds as {\sundials} packages do not use BLAS +directly. For third party libraries that require linking to BLAS, the path to +the BLAS library should be included in the \id{\_LIBRARIES} variable for the +third party library \textit{e.g.}, \id{SUPERLUDIST\_LIBRARIES} when enabling +SuperLU\_DIST. +% +\item Fixed a bug in the build system that prevented the {\nvecpthreads} module from +being built. +\end{itemize} -Added three new utility \id{N\_Vector} functions, \id{FN\_VGetVecAtIndexVectorArray}, -\id{FN\_VSetVecAtIndexVectorArray}, and \id{FN\_VNewVectorArray}, that are for -working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +\subsubsection*{NVECTOR module changes} -Fixed a bug in the {\kinsol} linear solver interface where the auxiliary scalar -\id{sJpnorm} was not computed when necessary with the Picard iteration and the -auxiliary scalar \id{sFdotJp} was unnecessarily computed in some cases. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\nvector} objects. The +constructor \id{N\_VNewEmpty} allocates an ``empty'' generic {\nvector} with the +object's content pointer and the function pointers in the operations structure +initialized to \id{NULL}. When used in the constructor for custom objects this +function will ease the introduction of any new optional operations to the +{\nvector} API by ensuring only required operations need to be set. +Additionally, the function \id{N\_VCopyOps(w, v)} has been added to copy the +operation function pointers between vector objects. When used in clone routines +for custom vector objects these functions also will ease the introduction of +any new optional operations to the {\nvector} API by ensuring all operations +are copied when cloning objects. See \S\ref{ss:nvecutils} for more details. +% +\item Two new {\nvector} implementations, {\nvecmanyvector} and +{\nvecmpimanyvector}, have been created to support flexible partitioning +of solution data among different processing elements (e.g., CPU + GPU) or for +multi-physics problems that couple distinct MPI-based simulations together. This +implementation is accompanied by additions to user documentation and {\sundials} +examples. See \S\ref{ss:nvec_manyvector} and \S\ref{ss:nvec_mpimanyvector} for +more details. +% +\item One new required vector operation and ten new optional vector operations have +been added to the {\nvector} API. The new required operation, \id{N\_VGetLength}, +returns the global length of an \id{N\_Vector}. The optional operations have +been added to support the new \newline\noindent +{\nvecmpimanyvector} implementation. The +operation \id{N\_VGetCommunicator} must be implemented by subvectors that are +combined to create an {\nvecmpimanyvector}, but is not used outside of +this context. The remaining nine operations are optional local reduction +operations intended to eliminate unnecessary latency when performing vector +reduction operations (norms, etc.) on distributed memory systems. The optional +local reduction vector operations are +\id{N\_VDotProdLocal}, +\id{N\_VMaxNormLocal}, +\id{N\_VMinLocal}, +\id{N\_VL1NormLocal}, +\id{N\_VWSqrSumLocal}, +\id{N\_VWSqrSumMaskLocal}, +\id{N\_VInvTestLocal}, +\id{N\_VConstrMaskLocal}, and +\id{N\_VMinQuotientLocal}. +If an {\nvector} implementation defines any of the local operations as +\id{NULL}, then the {\nvecmpimanyvector} will call standard {\nvector} +operations to complete the computation. See \S\ref{ss:nveclocalops} for more +details. +% +\item An additional {\nvector} implementation, {\nvecmpiplusx}, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism +(\textit{e.g.}, OpenMP, CUDA). The implementation is accompanied by additions to +user documentation and {\sundials} examples. See \S\ref{ss:nvec_mpiplusx} for +more details. +% +\item The \id{*\_MPICuda} and \id{*\_MPIRaja} functions have been removed from the +{\nveccuda} and {\nvecraja} implementations respectively. Accordingly, the +\id{nvector\_mpicuda.h}, \newline\noindent +\id{nvector\_mpiraja.h}, +\id{libsundials\_nvecmpicuda.lib}, and \id{libsundials\_nvecmpicudaraja.lib} +files have been removed. Users should use the {\nvecmpiplusx} module coupled +in conjunction with the {\nveccuda} or {\nvecraja} modules to replace the +functionality. The necessary changes are minimal and should require few +code modifications. See the programs in \id{examples/ida/mpicuda} and +\id{examples/ida/mpiraja} for examples of how to use the {\nvecmpiplusx} +module with the {\nveccuda} and {\nvecraja} modules respectively. +% +\item Fixed a memory leak in the {\nvecpetsc} module clone function. +% +\item Made performance improvements to the {\nveccuda} module. Users who utilize a +non-default stream should no longer see default stream synchronizations +after memory transfers. +% +\item Added a new constructor to the {\nveccuda} module that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. See \S\ref{ss:nvec_cuda_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\nvector} modules. See Chapter +\ref{s:nvector} for more details on how to use the interfaces. +% +\item Added three new {\nvector} utility functions, +\id{FN\_VGetVecAtIndexVectorArray},\newline\noindent +\id{FN\_VSetVecAtIndexVectorArray}, and +\id{FN\_VNewVectorArray}, +for working with \id{N\_Vector} arrays when using the Fortran 2003 interfaces. +See \S\ref{ss:nvecutils} for more details. +\end{itemize} -\subsection*{Changes in v5.0.0-dev.2} +\subsubsection*{SUNMatrix module changes} -Added a new optional operation to the SUNLINEARSOLVER API, \id{SUNLinSolGetID}, -that returns a \id{SUNLinearSolver\_ID} for identifying the linear solver -module. +\begin{itemize} +\item Two new functions were added to aid in creating custom {\sunmatrix} objects. The +constructor \id{SUNMatNewEmpty} allocates an ``empty'' generic {\sunmatrix} with +the object's content pointer and the function pointers in the operations +structure initialized to \id{NULL}. When used in the constructor for custom +objects this function will ease the introduction of any new optional operations +to the {\sunmatrix} API by ensuring only required operations need to be set. +Additionally, the function \id{SUNMatCopyOps(A, B)} has been added to copy the +operation function pointers between matrix objects. When used in clone routines +for custom matrix objects these functions also will ease the introduction of any +new optional operations to the {\sunmatrix} API by ensuring all operations are +copied when cloning objects. See \S\ref{ss:sunmatrix_utilities} for more details. +% +\item A new operation, \id{SUNMatMatvecSetup}, was added to the {\sunmatrix} API +to perform any setup necessary for computing a matrix-vector product. This +operation is useful for {\sunmatrix} implementations which need to prepare the +matrix itself, or communication structures before performing the matrix-vector +product. Users who have implemented custom {\sunmatrix} modules will need to at +least update their code to set the corresponding \id{ops} structure member, +\id{matvecsetup}, to \id{NULL}. See \S\ref{ss:sunmatrix_functions} for more +details. +% +\item The generic {\sunmatrix} API now defines error codes to be returned by +{\sunmatrix} operations. Operations which return an integer flag indiciating +success/failure may return different values than previously. See +\S\ref{ss:sunmatrix_ReturnCodes} for more details. +% +\item A new {\sunmatrix} (and {\sunlinsol}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunmat_slunrloc} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunmatrix} modules. See Chapter +\ref{s:sunmatrix} for more details on how to use the interfaces. +\end{itemize} -Made performance improvements to the {\nveccuda} module. Users who utilize a -non-default stream should no longer see default stream synchronizations after -memory transfers. +\subsubsection*{SUNLinearSolver module changes} -Added a new constructor to the {\nveccuda} module that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. - -Added a new SUNLinearSolver implementation, \id{SUNLinearSolver\_cuSolverSp\_batchQR}, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. - -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. - -The CMake option \id{BLAS\_ENABLE} and the variable \id{BLAS\_LIBRARIES} have -been removed to simplify builds as SUNDIALS packages do not use BLAS directly. -For third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the \id{\_LIBRARIES} variable for the third party -library e.g., \id{SUPERLUDIST\_LIBRARIES} when enabling SuperLU\_DIST. - -Added three new accessor functions to the {\sunlinsolklu} module, -\id{SUNLinSol\_KLUGetSymbolic}, \id{SUNLinSol\_KLUGetNumeric}, and -\id{SUNLinSol\_KLUGetCommon}, to provide user access to the underlying -{\klu} solver structures. - - -\subsection*{Changes in v5.0.0-dev.1} - -Several new functions were added to aid in creating custom {\nvector}, -{\sunmatrix}, {\sunlinsol}, and {\sunnonlinsol} objects. The constructors -\id{N\_VNewEmpty()}, \id{SUNMatNewEmpty()}, \id{SUNLinSolNewEmpty()}, and -\id{SUNNonlinSolNewEmpty()} allocate ``empty'' generic {\nvector}, {\sunmatrix}, -{\sunlinsol}, and {\sunnonlinsol} objects respectively with the object's content -pointer and the function pointers in the operations structure initialized to -\id{NULL}. When used in the constructor for custom objects these functions will -ease the introduction of any new optional operations to the {\nvector}, -{\sunmatrix}, {\sunlinsol}, or {\sunnonlinsol} APIs by ensuring only required -operations need to be set. Additionally, the functions \id{N\_VCopyOps(w, v)} -and \id{SUNMatCopyOps(A, B)} have been added to copy the operation function -pointers between vector and matrix objects respectively. When used in clone -routines for custom vector and matrix objects these functions also will ease the -introduction of any new optional operations to the {\nvector} or {\sunmatrix} -APIs by ensuring all operations are copied when cloning objects. - -The SUNLinearSolver API has been updated to make the initialize and setup +\begin{itemize} +\item A new function was added to aid in creating custom {\sunlinsol} objects. +The constructor \id{SUNLinSolNewEmpty} allocates an ``empty'' generic +{\sunlinsol} with the object's content pointer and the function pointers +in the operations structure initialized to \id{NULL}. When used in the +constructor for custom objects this function will ease the introduction of any +new optional operations to the {\sunlinsol} API by ensuring only required +operations need to be set. See \S\ref{ss:sunlinsol_custom} for more details. +% +\item The return type of the {\sunlinsol} API function \id{SUNLinSolLastFlag} +has changed from \id{long int} to \id{sunindextype} to be consistent with the +type used to store row indices in dense and banded linear solver modules. +% +\item Added a new optional operation to the {\sunlinsol} API, +\id{SUNLinSolGetID}, that returns a \newline\noindent +\id{SUNLinearSolver\_ID} for identifying the +linear solver module. +% +\item The {\sunlinsol} API has been updated to make the initialize and setup functions optional. +% +\item A new {\sunlinsol} (and {\sunmatrix}) implementation was added to +facilitate the use of the SuperLU\_DIST library with {\sundials}. See +\S\ref{ss:sunlinsol_sludist} for more details. +% +\item Added a new {\sunlinsol} implementation, +\id{SUNLinearSolver\_cuSolverSp\_batchQR}, which leverages the NVIDIA cuSOLVER +sparse batched QR method for efficiently solving block diagonal linear systems +on NVIDIA GPUs. See \S\ref{ss:sunlinsol_cuspbqr} for more details. +% +\item Added three new accessor functions to the {\sunlinsolklu} module, +\id{SUNLinSol\_KLUGetSymbolic}, +\id{SUNLinSol\_KLUGetNumeric}, and +\id{SUNLinSol\_KLUGetCommon}, +to provide user access to the underlying KLU solver structures. See +\S\ref{ss:sunlinsol_klu_functions} for more details. +% +\item Added new Fortran 2003 interfaces for most {\sunlinsol} modules. See +Chapter \ref{s:sunlinsol} for more details on how to use the interfaces. +\end{itemize} -The KINLS interface has been updated to only zero the Jacobian matrix before -calling a user-supplied Jacobian evaluation function when the attached linear -solver has type \id{SUNLINEARSOLVER\_DIRECT}. - -Fixed a bug in the build system that prevented the {\nvecpthreads} module from -being built. +\subsubsection*{KINSOL changes} -Fixed a memory leak in the {\nvecpetsc} clone function. - -The {\nvecmanyvector} module has been split into two versions: one -that requires MPI ({\nvecmpimanyvector}) and another that does not use -MPI at all ({\nvecmanyvector}). The associated example problems have -been similarly updated to reflect this new structure. - -An additional {\nvector} implementation, {\nvecmpiplusx}, was created to support -the MPI+X paradigm, where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and {\sundials} -examples. - -The \id{*\_MPICuda} and \id{*\_MPIRaja} functions were removed from the {\nveccuda} and -{\nvecraja} implementations respectively. Accordingly, the \id{nvector\_mpicuda.h}, -\id{nvector\_mpiraja.h}, \id{libsundials\_nvecmpicuda.lib}, and~ -\id{libsundials\_nvecmpicudaraja.lib} files have been removed. Users should use -the {\nvecmpiplusx} module coupled with {\nveccuda} or {\nvecraja} to replace the -functionality. The necessary changes are minimal and should require few code -modifications. - -A new Fortran 2003 interface to {\kinsol} was added. This includes Fortran 2003 interfaces -to all generic {\sundials} types (i.e. {\nvector}, {\sunmatrix}, {\sunlinsol}, {\sunnonlinsol}), -and many of the module implementations. See Section~\ref{s:kinfort} for more details. +\begin{itemize} +\item Fixed a bug in the {\kinsol} linear solver interface where the auxiliary scalar +\id{sJpnorm} was not computed when necessary with the Picard iteration and the +auxiliary scalar \id{sFdotJp} was unnecessarily computed in some cases. +% +\item The KINLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type \newline\noindent +\id{SUNLINEARSOLVER\_DIRECT}. +% +\item Added a Fortran 2003 interface to {\kinsol}. See Chapter~\ref{s:kinfort} +for more details. +\end{itemize} \subsection*{Changes in v5.0.0-dev.0} diff --git a/doc/sundials/biblio.bib b/doc/sundials/biblio.bib index 13ed9763d5..d163752939 100644 --- a/doc/sundials/biblio.bib +++ b/doc/sundials/biblio.bib @@ -16,7 +16,7 @@ @techreport{arkode_ug, author={Daniel R. Reynolds and David J. Gardner and Alan C. Hindmarsh and Carol S. Woodward and Jean M. Sexton}, -title={{User Documentation for ARKODE v4.0.0-dev.2}}, +title={{User Documentation for ARKODE v4.0.0}}, institution={LLNL}, number={LLNL-SM-668082}, year=2019 @@ -26,7 +26,7 @@ @techreport{arkode_ug % @techreport{arkode_ex, author={Daniel R. Reynolds}, -title={{Example Programs for ARKODE v4.0.0-dev.2}}, +title={{Example Programs for ARKODE v4.0.0}}, institution={Southern Methodist University}, year=2019 } @@ -35,7 +35,7 @@ @techreport{arkode_ex % @techreport{cvode_ug, author={A. C. Hindmarsh and R. Serban}, -title={{User Documentation for CVODE v5.0.0-dev.2}}, +title={{User Documentation for CVODE v5.0.0}}, institution={LLNL}, number={UCRL-SM-208108}, year=2019 @@ -45,7 +45,7 @@ @techreport{cvode_ug % @techreport{cvode_ex, author={A. C. Hindmarsh and R. Serban and D. R. Reynolds}, -title={{Example Programs for CVODE v5.0.0-dev.2}}, +title={{Example Programs for CVODE v5.0.0}}, institution={LLNL}, note={UCRL-SM-208110}, year=2019 @@ -55,7 +55,7 @@ @techreport{cvode_ex % @techreport{cvodes_ug, author={A. C. Hindmarsh and R. Serban}, -title={{User Documentation for CVODES v5.0.0-dev.2}}, +title={{User Documentation for CVODES v5.0.0}}, institution={LLNL}, note={UCRL-SM-208111}, year=2019 @@ -65,7 +65,7 @@ @techreport{cvodes_ug % @techreport{cvodes_ex, author={R. Serban and A. C. Hindmarsh}, -title={{Example Programs for CVODES v5.0.0-dev.2}}, +title={{Example Programs for CVODES v5.0.0}}, institution={LLNL}, number={UCRL-SM-208115}, year=2019 @@ -75,7 +75,7 @@ @techreport{cvodes_ex % @techreport{ida_ug, author={A. C. Hindmarsh and R. Serban and A. Collier}, -title={{User Documentation for IDA v5.0.0-dev.2}}, +title={{User Documentation for IDA v5.0.0}}, institution={LLNL}, number={UCRL-SM-208112}, year=2019 @@ -85,7 +85,7 @@ @techreport{ida_ug % @techreport{ida_ex, author={A. C. Hindmarsh and R. Serban and A. Collier}, -title={{Example Programs for IDA v5.0.0-dev.2}}, +title={{Example Programs for IDA v5.0.0}}, institution={LLNL}, number={UCRL-SM-208113}, year=2019 @@ -95,7 +95,7 @@ @techreport{ida_ex % @techreport{idas_ug, author={R. Serban and C. Petra and A. C. Hindmarsh}, -title={{User Documentation for IDAS v4.0.0-dev.2}}, +title={{User Documentation for IDAS v4.0.0}}, institution={LLNL}, number={UCRL-SM-234051}, year=2019 @@ -105,7 +105,7 @@ @techreport{idas_ug % @techreport{idas_ex, author={R. Serban and A. C. Hindmarsh}, -title={{Example Programs for IDAS v4.0.0-dev.2}}, +title={{Example Programs for IDAS v4.0.0}}, institution={LLNL}, number={LLNL-TR-437091}, year=2019 @@ -115,7 +115,7 @@ @techreport{idas_ex % @techreport{kinsol_ug, author={A. M. Collier and A. C. Hindmarsh and R. Serban and C.S. Woodward}, -title={{User Documentation for KINSOL v5.0.0-dev.2}}, +title={{User Documentation for KINSOL v5.0.0}}, institution={LLNL}, number={UCRL-SM-208116}, year=2019 @@ -125,7 +125,7 @@ @techreport{kinsol_ug % @techreport{kinsol_ex, author={A. M. Collier and R. Serban}, -title={{Example Programs for KINSOL v5.0.0-dev.2}}, +title={{Example Programs for KINSOL v5.0.0}}, institution={LLNL}, number={UCRL-SM-208114}, year=2019 diff --git a/doc/sundials/sundials_release_history.tex b/doc/sundials/sundials_release_history.tex index 036092aa87..3b05f4f6e0 100644 --- a/doc/sundials/sundials_release_history.tex +++ b/doc/sundials/sundials_release_history.tex @@ -17,9 +17,7 @@ \chapter{SUNDIALS Release History} $^3${\cvode} and {\pvode} combined, $^4${\ida} written, $^5${\kinsol} written}\\ \hline} \begin{xtabular}{|ll|c|c|c|c|c|c|c|} %% Version Table -Sep & 2019 & 5.0.0-dev.2 & 4.0.0-dev.2 & 5.0.0-dev.2 & 5.0.0-dev.2 & 5.0.0-dev.2 & 4.0.0-dev.2 & 5.0.0-dev.2 \\ -Jun & 2019 & 5.0.0-dev.1 & 4.0.0-dev.1 & 5.0.0-dev.1 & 5.0.0-dev.1 & 5.0.0-dev.1 & 4.0.0-dev.1 & 5.0.0-dev.1 \\ -Mar & 2019 & 5.0.0-dev.0 & 4.0.0-dev.0 & 5.0.0-dev.0 & 5.0.0-dev.0 & 5.0.0-dev.0 & 4.0.0-dev.0 & 5.0.0-dev.0\\ +Oct & 2019 & 5.0.0 & 4.0.0 & 5.0.0 & 5.0.0 & 5.0.0 & 4.0.0 & 5.0.0\\ Feb & 2019 & 4.1.0 & 3.1.0 & 4.1.0 & 4.1.0 & 4.1.0 & 3.1.0 & 4.1.0\\ Jan & 2019 & 4.0.2 & 3.0.2 & 4.0.2 & 4.0.2 & 4.0.2 & 3.0.2 & 4.0.2\\ Dec & 2018 & 4.0.1 & 3.0.1 & 4.0.1 & 4.0.1 & 4.0.1 & 3.0.1 & 4.0.1\\ diff --git a/doc/sundials/ug.tex b/doc/sundials/ug.tex index 31892ee834..62477f1a0a 100644 --- a/doc/sundials/ug.tex +++ b/doc/sundials/ug.tex @@ -59,29 +59,29 @@ %----- VERSIONS AND UCRL NUMBERS OF SUNDIALS CODES -\newcommand{\sunrelease}{v5.0.0-dev.2} +\newcommand{\sunrelease}{v5.0.0} -\newcommand{\cvrelease}{v5.0.0-dev.2} +\newcommand{\cvrelease}{v5.0.0} \newcommand{\cvucrlug}{UCRL-SM-208108} \newcommand{\cvucrlex}{UCRL-SM-208110} -\newcommand{\cvsrelease}{v5.0.0-dev.2} +\newcommand{\cvsrelease}{v5.0.0} \newcommand{\cvsucrlug}{UCRL-SM-208111} \newcommand{\cvsucrlex}{UCRL-SM-208115} -\newcommand{\idarelease}{v5.0.0-dev.2} +\newcommand{\idarelease}{v5.0.0} \newcommand{\idaucrlug}{UCRL-SM-208112} \newcommand{\idaucrlex}{UCRL-SM-208113} -\newcommand{\idasrelease}{v4.0.0-dev.2} +\newcommand{\idasrelease}{v4.0.0} \newcommand{\idasucrlug}{UCRL-SM-234051} \newcommand{\idasucrlex}{LLNL-TR-437091} -\newcommand{\kinrelease}{v5.0.0-dev.2} +\newcommand{\kinrelease}{v5.0.0} \newcommand{\kinucrlug}{UCRL-SM-208116} \newcommand{\kinucrlex}{UCRL-SM-208114} -\newcommand{\arkrelease}{v4.0.0-dev.2} +\newcommand{\arkrelease}{v4.0.0} \newcommand{\arkucrlug}{LLNL-SM-668082} \newcommand{\arkucrlex}{????-??-??????} diff --git a/recent_changes.md b/recent_changes.md index 5729e0d9bd..83183fcfa4 100644 --- a/recent_changes.md +++ b/recent_changes.md @@ -2,22 +2,157 @@ ## Changes to SUNDIALS in release 5.0.0 +### Build System + +Increased the minimum required CMake version to 3.5 for most SUNDIALS +configurations, and 3.10 when CUDA or OpenMP with device offloading are enabled. + +The CMake option `BLAS_ENABLE` and the variable `BLAS_LIBRARIES` have been +removed to simplify builds as SUNDIALS packages do not use BLAS directly. For +third party libraries that require linking to BLAS, the path to the BLAS +library should be included in the `_LIBRARIES` variable for the third party +library e.g., `SUPERLUDIST_LIBRARIES` when enabling SuperLU_DIST. + +Fixed a bug in the build system that prevented the PThreads NVECTOR module from +being built. + +### NVector + +Two new functions were added to aid in creating custom NVECTOR objects. The +constructor N_VNewEmpty() allocates an ``empty'' generic NVECTOR with the +object's content pointer and the function pointers in the operations structure +initialized to NULL. When used in the constructor for custom objects this function +will ease the introduction of any new optional operations to the NVECTOR API by +ensuring only required operations need to be set. Additionally, the function +N_VCopyOps(w, v) has been added to copy the operation function pointers between +vector objects. When used in clone routines for custom vector objects these +functions also will ease the introduction of any new optional operations to the +NVECTOR API by ensuring all operations are copied when cloning objects. + +Two new N_Vector implementations, NVECTOR_MANYVECTOR and NVECTOR_MPIMANYVECTOR, +have been created to support flexible partitioning of solution data among +different processing elements (e.g., CPU + GPU) or for multi-physics problems +that couple distinct MPI-based simulations together (see the NVECTOR_MANYVECTOR +and NVECTOR_MPIMANYVECTOR sections in the user guides for more details). This +implementation is accompanied by additions to user documentation and SUNDIALS +examples. + +An additional NVECTOR implementation, NVECTOR_MPIPLUSX, has been created to +support the MPI+X paradigm where X is a type of on-node parallelism (e.g., +OpenMP, CUDA). The implementation is accompanied by additions to user +documentation and SUNDIALS examples. + +One new required vector operation and ten new optional vector operations have +been added to the NVECTOR API. The new required operation, N_VGetLength, returns +the global length of an N_Vector. The optional operations have been added to +support the new NVECTOR_MPIMANYVECTOR implementation. The operation +N_VGetCommunicator must be implemented by subvectors that are combined to create +an NVECTOR_MPIMANYVECTOR, but is not used outside of this context. The +remaining nine operations are optional local reduction operations intended to +eliminate unnecessary latency when performing vector reduction operations +(norms, etc.) on distributed memory systems. The optional local reduction vector +operations are N_VDotProdLocal, N_VMaxNormLocal, N_VMinLocal, N_VL1NormLocal, +N_VWSqrSumLocal, N_VWSqrSumMaskLocal, N_VInvTestLocal, N_VConstrMaskLocal, and +N_VMinQuotientLocal. If an NVECTOR implementation defines any of the local +operations as NULL, then the NVECTOR_MPIMANYVECTOR will call standard NVECTOR +operations to complete the computation. + +The *_MPICuda and *_MPIRaja functions have been removed from the NVECTOR_CUDA +and NVECTOR_RAJA implementations respectively. Accordingly, the +nvector_mpicuda.h, nvector_mpiraja.h, libsundials_nvecmpicuda.lib, and +libsundials_nvecmpicudaraja.lib files have been removed. Users should use the +NVECTOR_MPIPLUSX module in conjunction with the NVECTOR_CUDA or NVECTOR_RAJA +modules to replace the functionality. The necessary changes are minimal and +should require few code modifications. + +Fixed a memory leak in the NVECTOR_PETSC clone function. + +Made performance improvements to the CUDA NVECTOR. Users who utilize a non +-default stream should no longer see default stream synchronizations after +memory transfers. + +Added a new constructor to the CUDA NVECTOR that allows a user to provide +custom allocate and free functions for the vector data array and internal +reduction buffer. + +Added new Fortran 2003 interfaces for most NVECTOR modules. See NEVTOR section +in the user guides for more details on how to use the interfaces. + +Added three new NVECTOR utility functions, `FN_VGetVecAtIndexVectorArray`, +`FN_VSetVecAtIndexVectorArray`, and `FN\_VNewVectorArray`, for working with +`N_Vector` arrays when using the Fortran 2003 interfaces. + +### SUNMatrix + +Two new functions were added to aid in creating custom SUNMATRIX objects. The +constructor SUNMatNewEmpty() allocates an ``empty'' generic SUNMATRIX with the +object's content pointer and the function pointers in the operations structure +initialized to NULL. When used in the constructor for custom objects this function +will ease the introduction of any new optional operations to the SUNMATRIX API by +ensuring only required operations need to be set. Additionally, the function +SUNMatCopyOps(A, B) has been added to copy the operation function pointers between +matrix objects. When used in clone routines for custom matrix objects these +functions also will ease the introduction of any new optional operations to the +SUNMATRIX API by ensuring all operations are copied when cloning objects. + +A new operation, SUNMatMatvecSetup, was added to the SUNMatrix API. Users +who have implemented custom SUNMatrix modules will need to at least update +their code to set the corresponding ops structure member, matvecsetup, to NULL. + +The generic SUNMatrix API now defines error codes to be returned by SUNMatrix operations. +Operations which return an integer flag indiciating success/failure may return different +values than previously. + +A new SUNMatrix (and SUNLinearSolver) implementation was added to facilitate +the use of the SuperLU_DIST library with SUNDIALS. + +Added new Fortran 2003 interfaces for most SUNMATRIX modules. See SUNMATRIX +section in the user guides for more details on how to use the interfaces. + +### SUNLinearSolver + +A new function was added to aid in creating custom SUNLINEARSOLVER objects. The +constructor SUNLinSolNewEmpty() allocates an ``empty'' generic SUNLINEARSOLVER +with the object's content pointer and the function pointers in the operations +structure initialized to NULL. When used in the constructor for custom objects +this function will ease the introduction of any new optional operations to the +SUNLINEARSOLVER API by ensuring only required operations need to be set. + The return type of the SUNLinearSolver API function `SUNLinSolLastFlag` has changed from `long int` to `sunindextype` to be consistent with the type used to store row indices in dense and banded linear solver modules. -Added Fortran 2003 interfaces to CVODES and IDAS. +Added a new optional operation to the SUNLINEARSOLVER API, `SUNLinSolGetID`, +that returns a `SUNLinearSolver_ID` for identifying the linear solver module. -Added Fortran 2003 interfaces to the `NVECTOR_MANYVECTOR`, -`NVECTOR_MPIMANYVECTOR` and `NVECTOR_MPIPLUSX` `N\_Vector` -implementations. +The SUNLinearSolver API has been updated to make the initialize and setup +functions optional. -Added three new utility N_Vector functions, `FN_VAtIndexVectorArray`, -`FN_VSetAtIndexVectorArray`, and `FN_VNewVectorArray`, that are for working -with N_Vector arrays when using the Fortran 2003 interfaces. +A new SUNLinearSolver (and SUNMatrix) implementation was added to facilitate +the use of the SuperLU_DIST library with SUNDIALS. -Added a new `SUNNonlinearSolver` implementation, `SUNNonlinsol_PetscSNES`, -which interfaces to the PETSc SNES nonlinear solver API. +Added a new SUNLinearSolver implementation, `SUNLinearSolver_cuSolverSp_batchQR`, +which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently +solving block diagonal linear systems on NVIDIA GPUs. + +Added three new accessor functions to the SUNLinSol_KLU module, +`SUNLinSol_KLUGetSymbolic()`, `SUNLinSol_KLUGetNumeric()`, and +`SUNLinSol_KLUGetCommon()`, to provide user access to the underlying +KLU solver structures. + +Added new Fortran 2003 interfaces for most SUNLINEARSOLVER modules. See +SUNLINEARSOLVER section in the user guides for more details on how to use +the interfaces. + +### SUNNonlinearSolver + +A new function was added to aid in creating custom SUNNONLINEARSOLVER objects. +The constructor SUNNonlinSolNewEmpty() allocates an ``empty'' generic +SUNNONLINEARSOLVER with the object's content pointer and the function pointers +in the operations structure initialized to NULL. When used in the constructor +for custom objects this function will ease the introduction of any new optional +operations to the SUNNONLINEARSOLVER API by ensuring only required operations +need to be set. To facilitate the use of user supplied nonlinear solver convergence test functions the `SUNNonlinSolSetConvTestFn` function in the SUNNonlinearSolver API @@ -25,205 +160,179 @@ has been updated to take a `void*` data pointer as input. The supplied data pointer will be passed to the nonlinear solver convergence test function on each call. -The definitions of `SUNNonlinSolLSetupFn` and `SUNNonlinSolLSolveFn` in the +The inputs values passed to the first two inputs of the `SUNNonlinSolSolve` +function in the SUNNONLINEARSOLVER have been changed to be the predicted +state and the initial guess for the correction to that state. Additionally, +the definitions of `SUNNonlinSolLSetupFn` and `SUNNonlinSolLSolveFn` in the SUNNonlinearSolver API have been updated to remove unused input parameters. +For more information on the nonlinear system formulation and the API functions +see the SUNNONLINEARSOLVER chapter in the user guides. -Support for optional inequality constraints on individual components of the -solution vector has been added the ARKode ERKStep and ARKStep modules. See -the descriptions of ERKStepSetConstraints and ARKStepSetConstraints for -more details. Note that enabling constraint handling requires the NVECTOR -operations N_VMinQuotient, N_VConstrMask, and N_VCompare that were not -previously required by ARKode. +Added a new `SUNNonlinearSolver` implementation, `SUNNonlinsol_PetscSNES`, +which interfaces to the PETSc SNES nonlinear solver API. + +Added new Fortran 2003 interfaces for most SUNNONLINEARSOLVER modules. See +SUNNONLINEARSOLVER section in the user guides for more details on how to use +the interfaces. + +### CVODE and CVODES Fixed a bug in the CVODE and CVODES constraint handling where the step size could be set below the minimum step size. -Fixed a bug in ARKode that would result in a "too much accuracy requested" error -when using fixed time step sizes with explicit methods in some cases. - -Fixed a bug in the KINSOL linear solver interface where the auxiliary scalar -`sJpnorm` was not computed when necessary with the Picard iteration and the -auxiliary scalar `sFdotJp` was unnecessarily computed in some cases. +Fixed a bug in the CVODE and CVODES nonlinear solver interfaces where the norm +of the accumulated correction was not updated when using a non-default +convergence test function. Fixed a bug in the CVODES `cvRescale` function where the loops to compute the array of scalars for the fused vector scale operation stopped one iteration early. -Fixed a bug in CVODES and IDAS where CVodeF and IDASolveF would return the wrong -flag under certain cirumstances. +Fixed a bug in CVODES where CVodeF would return the wrong flag under certain +cirumstances. -Fixed a bug in CVODES and IDAS where CVodeF and IDASolveF would not return a -root in NORMAL_STEP mode if the root occurred after the desired output time. +Fixed a bug in CVODES where CVodeF would not return a root in NORMAL_STEP mode +if the root occurred after the desired output time. -## Changes to SUNDIALS in release 5.0.0-dev.2 +Fixed a memeory leak in FCVODE when not using the default nonlinear solver. -Added a new optional operation to the SUNLINEARSOLVER API, `SUNLinSolGetID`, -that returns a `SUNLinearSolver_ID` for identifying the linear solver module. +Removed extraneous calls to N_VMin() for simulations where the scalar valued +absolute tolerance, or all entries of the vector-valued absolute tolerance +array, are strictly positive. In this scenario CVODE and CVODES will remove +at least one global reduction per time step. -Made performance improvements to the CUDA NVECTOR. Users who utilize a non --default stream should no longer see default stream synchronizations after -memory transfers. +The CVLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type `SUNLINEARSOLVER_DIRECT`. -Added a new constructor to the CUDA NVECTOR that allows a user to provide -custom allocate and free functions for the vector data array and internal -reduction buffer. +A new linear solver interface function, `CVLsLinSysFn`, was added as an +alternative method for evaluating the linear systems I - gamma J. -Increased the minimum required CMake version to 3.5 for most SUNDIALS configurations, -and 3.10 when CUDA or OpenMP with device offloading are enabled. +Added functions to get the current state and gamma value to CVODE and CVODES. +These functions may be useful to users who chose to provide their own nonlinear +solver implementation. -The CMake option `BLAS_ENABLE` and the variable `BLAS_LIBRARIES` have been -removed to simplify builds as SUNDIALS packages do not use BLAS directly. For -third party libraries that require linking to BLAS, the path to the BLAS -library should be included in the `_LIBRARIES` variable for the third party -library e.g., `SUPERLUDIST_LIBRARIES` when enabling SuperLU_DIST. +Added New Fortran 2003 interfaces to CVODE and CVODES were added. These new +interfaces were generated with SWIG-Fortran and provide a user an idiomatic +Fortran 2003 interface to most of the SUNDIALS C API. The existing CVODE F2003 +interface, and all module implementations with existing Fortran 2003 interfaces +were updated accordingly. See the section "Using CVODE for Fortran +Applications" and "Using CVODES for Fortran Applications" in the appropriate +user guide for more details on how to use the interfaces. + +### ARKode + +The MRIStep module has been updated to support explicit, implicit, or IMEX +methods as the fast integrator using the ARKStep module. As a result some +function signatures have been changed including MRIStepCreate which now +takes an ARKStep memory structure for the fast integration as an input. Fixed a bug in the ARKStep time-stepping module in ARKode that would result in an infinite loop if the nonlinear solver failed to converge more than the maximum allowed times during a single step. -Added functions to get the current state and gamma value to CVODE(S) and ARKode. -These functions may be useful to users who chose to provide their own nonlinear -solver implementation. +Fixed a bug in ARKode that would result in a "too much accuracy requested" error +when using fixed time step sizes with explicit methods in some cases. -Add two new 'Set' functions to MRIStep, `MRIStepSetPreInnerFn()` and -`MRIStepSetPostInnerFn()` for performing communication or memory -transfers needed before or after the inner integration. +Fixed a bug in ARKStep where the mass matrix linear solver setup function was +not called in the Matrix-free case. + +Fixed a minor bug in ARKStep where an incorrect flag is reported when an +error occurs in the mass matrix setup or Jacobian-vector product setup +functions. + +Fixed a memeory leak in FARKODE when not using the default nonlinear solver. The reinitialization functions `ERKStepReInit()`, `ARKStepReInit()`, and `MRIStepReInit()` have been updated to retain the minimum and maxiumum step size values from before reinitialization rather than resetting them to the default values. -Added a new SUNLinearSolver implementation, `SUNLinearSolver_cuSolverSp_batchQR`, -which leverages the NVIDIA cuSOLVER sparse batched QR method for efficiently -solving block diagonal linear systems on NVIDIA GPUs. +Removed extraneous calls to N_VMin() for simulations where the scalar valued +absolute tolerance, or all entries of the vector-valued absolute tolerance +array, are strictly positive. In this scenario ARKode steppers will remove +at least one global reduction per time step. -Added three new accessor functions to the SUNLinSol_KLU module, -`SUNLinSol_KLUGetSymbolic()`, `SUNLinSol_KLUGetNumeric()`, and -`SUNLinSol_KLUGetCommon()`, to provide user access to the underlying -KLU solver structures. +The ARKLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type `SUNLINEARSOLVER_DIRECT`. -A bug was fixed in the IDA(S) linear solver interface where an incorrect -Jacobian-vector product increment was used with iterative solvers other than -SPGMR and SPFGMR. +A new linear solver interface function, `ARKLsLinSysFn`, was added as an +alternative method for evaluating the linear systems M - gamma J and +I - gamma J. -Fixed a bug in the CVODE(S) nonlinear solver interface where the norm of the -accumulated correction was not updated when using a non-default convergence -test function. - -## Changes to SUNDIALS in release 5.0.0-dev.1 - -Several new functions were added to aid in creating custom NVECTOR, -SUNMATRIX, SUNLINEARSOLVER, and SUNNONLINEARSOLVER objects. The constructors -N_VNewEmpty(), SUNMatNewEmpty(), SUNLinSolNewEmpty(), and SUNNonlinSolNewEmpty() -allocate ``empty'' generic NVECTOR, SUNMATRIX, SUNLINEARSOLVER, and -SUNNONLINEARSOLVER objects respectively with the object's content pointer and -the function pointers in the operations structure initialized to NULL. When used -in the constructor for custom objects these functions will ease the introduction -of any new optional operations to the NVECTOR, SUNMATRIX, SUNLINEARSOLVER, or -SUNNONLINEARSOLVER APIs by ensuring only required operations need to be set. -Additionally, the functions N_VCopyOps(w, v) and SUNMatCopyOps(A, B) have been -added to copy the operation function pointers between vector and matrix objects -respectively. When used in clone routines for custom vector and matrix objects -these functions also will ease the introduction of any new optional operations -to the NVECTOR or SUNMATRIX APIs by ensuring all operations are copied when -cloning objects. - -New linear solver interface functions ARKLsLinSysFn and CVLsLinSysFn were added -as alternative methods for evaluating the linear systems M - gamma J and -I - gamma J respectively. +Added two new embedded ARK methods of orders 4 and 5 to ARKode (from +Kennedy & Carpenter, Appl. Numer. Math., 136:183--205, 2019). -Fixed a bug in the build system that prevented the PThreads NVECTOR module from -being built. +Support for optional inequality constraints on individual components of the +solution vector has been added the ARKode ERKStep and ARKStep modules. See +the descriptions of ERKStepSetConstraints and ARKStepSetConstraints for +more details. Note that enabling constraint handling requires the NVECTOR +operations N_VMinQuotient, N_VConstrMask, and N_VCompare that were not +previously required by ARKode. -Fixed a bug in ARKStep where the mass matrix linear solver setup function was -not called in the Matrix-free case. +Added functions to get the current state and gamma value to the ARKStep module. +These functions may be useful to users who chose to provide their own nonlinear +solver implementation. -Fixed a minor bug in ARKStep where an incorrect flag is reported when an -error occurs in the mass matrix setup or Jacobian-vector product setup -functions. +Add two new 'Set' functions to MRIStep, `MRIStepSetPreInnerFn()` and +`MRIStepSetPostInnerFn()` for performing communication or memory +transfers needed before or after the inner integration. -Fixed a memory leak in the NVECTOR_PETSC clone function. +Added new Fortran 2003 interfaces to all ARKode stepper modules. These new +interfaces were generated with SWIG-Fortran and provide a user an idiomatic +Fortran 2003 interface to most of the SUNDIALS C API. See the section "Using +ARKode for Fortran Applications" in the user guide for more details on how +to use the interfaces. -Fixed a memeory leaks in FARKODE, FCVODE, and FIDA when not using the default -nonlinear solver. +### IDA and IDAS -Fixed a bug in IDAQuadReInitB where an incorrect memory structure was passed to -IDAQuadReInit. +A bug was fixed in the IDA and IDAS linear solver interfaces where an incorrect +Jacobian-vector product increment was used with iterative solvers other than +SPGMR and SPFGMR. -Added two new embedded ARK methods of orders 4 and 5 to ARKode (from -Kennedy & Carpenter, Appl. Numer. Math., 136:183--205, 2019). +Fixed a bug in IDAS where IDASolveF would return the wrong flag under certain +cirumstances. -The ManyVector NVECTOR module has been split into two versions: one -that requires MPI (MPIManyVector) and another that does not use -MPI at all (ManyVector). The associated example problems have -been similarly updated to reflect this new structure. +Fixed a bug in IDAS where IDASolveF would not return a root in NORMAL_STEP mode +if the root occurred after the desired output time. -An additional NVECTOR implementation, NVECTOR_MPIPLUSX, was created to support -the MPI+X paradigm where X is a type of on-node parallelism (e.g. OpenMP, CUDA). -The implementation is accompanied by additions to user documentation and SUNDIALS -examples. +Fixed a bug the IDAS IDAQuadReInitB function where an incorrect memory structure +was passed to IDAQuadReInit. -The *_MPICuda and *_MPIRaja functions were removed from the NVECTOR_CUDA and -NVECTOR_RAJA implementations respectively. Accordingly, the nvector_mpicuda.h, -nvector_mpiraja.h, libsundials_nvecmpicuda.lib, and libsundials_nvecmpicudaraja.lib -files have been removed. Users should use the NVECTOR_MPIPLUSX module coupled with -the NVECTOR_CUDA or NVECTOR_RAJA to replace the functionality. The necessary changes -are minimal and should require few code modifications. - -New Fortran 2003 interfaces to ARKODE, IDA, KINSOL, all generic SUNDIALS types -(i.e. NVECTOR, SUNMATRIX, SUNLINEARSOLVER, SUNNONLINEARSOLVER), and the -NVECTOR_PARALLEL were added. These new interfaces were generated with SWIG-Fortran -and provide a user an idiomatic Fortran 2003 interface to most of the SUNDIALS C API. -The CVODE interface, and all module implementations with existing Fortran 2003 interfaces -were updated accordingly. See the section "Using \ for Fortran Applications" in -the appropriate user guide for more details on how to use the interfaces. - -Removed extraneous calls to N_VMin() for simulations where -the scalar valued absolute tolerance, or all entries of the -vector-valued absolute tolerance array, are strictly positive. In -this scenario, CVODE(S), IDA(S) and ARKode will remove at least one -global reduction per time step. - -## Changes to SUNDIALS in release 5.0.0-dev.0 - -An additional N_Vector implementation, NVECTOR_MANYVECTOR, was -created to support flexible partitioning of solution data among -different processing elements (e.g., CPU + GPU) or for multi-physics -problems that couple distinct MPI-based simulations together (see -the NVECTOR_MANYVECTOR section in the user guides for more details). -This implementation is accompanied by additions to user documentation -and SUNDIALS examples. - -Eleven new optional vector operations have been added to the N_Vector API to -support the new NVECTOR_MANYVECTOR implementation (see N_Vector chapter is the -user guides for more details). Two of the operations, N_VGetCommunicator and -N_VGetLength, must be implemented by subvectors that are combined to create an -NVECTOR_MANYVECTOR, but are not used outside of this context. The remaining nine -operations are optional local reduction operations intended to eliminate -unnecessary latency when performing vector reduction operations (norms, etc.) on -distributed memory systems. The optional local reduction vector operations are -N_VDotProdLocal, N_VMaxNormLocal, N_VMinLocal, N_VL1NormLocal, N_VWSqrSumLocal, -N_VWSqrSumMaskLocal, N_VInvTestLocal, N_VConstrMaskLocal, and -N_VMinQuotientLocal. If an N_Vector implementation defines any of the local -operations as NULL, then the NVECTOR_MANYVECTOR will call standard N_Vector -operations to complete the computation. +Fixed a memeory leak in FIDA when not using the default nonlinear solver. -A new SUNMatrix and SUNLinearSolver implementation was added to facilitate -the use of the SuperLU_DIST library with SUNDIALS. +Removed extraneous calls to N_VMin() for simulations where the scalar valued +absolute tolerance, or all entries of the vector-valued absolute tolerance +array, are strictly positive. In this scenario IDA and IDAS will remove +at least one global reduction per time step. -A new operation, SUNMatMatvecSetup, was added to the SUNMatrix API. Users -who have implemented custom SUNMatrix modules will need to at least update -their code to set the corresponding ops structure member, matvecsetup, to NULL. +The IDALS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type SUNLINEARSOLVER_DIRECT. + +Added new Fortran 2003 interfaces to IDA and IDAS. These new interfaces were +generated with SWIG-Fortran and provide a user an idiomatic Fortran 2003 +interface to most of the SUNDIALS C API. See the section "Using IDA for Fortran +Applications" and "Using IDAS for Fortran Applications" in the appropriate +user guide for more details on how to use the interfaces. + +### KINSOL + +Fixed a bug in the KINSOL linear solver interface where the auxiliary scalar +`sJpnorm` was not computed when necessary with the Picard iteration and the +auxiliary scalar `sFdotJp` was unnecessarily computed in some cases. + +The KINLS interface has been updated to only zero the Jacobian matrix before +calling a user-supplied Jacobian evaluation function when the attached linear +solver has type SUNLINEARSOLVER_DIRECT. + +Added new Fortran 2003 interfaces to KINSOL. These new interfaces were +generated with SWIG-Fortran and provide a user an idiomatic Fortran 2003 +interface to most of the SUNDIALS C API. See the section "Using KINSOL for +Fortran Applications" for more details on how to use the interfaces. -The generic SUNMatrix API now defines error codes to be returned by SUNMatrix operations. -Operations which return an integer flag indiciating success/failure may return different -values than previously. -The MRIStep module has been updated to support explicit, implicit, or IMEX -methods as the fast integrator using the ARKStep module. As a result some -function signatures have been changed including MRIStepCreate which now -takes an ARKStep memory structure for the fast integration as an input. ## Changes to SUNDIALS in release 4.1.0 diff --git a/scripts/tarscript b/scripts/tarscript index 212cc241c5..499ee5d731 100755 --- a/scripts/tarscript +++ b/scripts/tarscript @@ -43,13 +43,13 @@ function print_usage # VERSION NUMBERS #--------------------------------------------------------- -SUN_VER="5.0.0-dev.2" -CV_VER="5.0.0-dev.2" -CVS_VER="5.0.0-dev.2" -IDA_VER="5.0.0-dev.2" -IDAS_VER="4.0.0-dev.2" -KIN_VER="5.0.0-dev.2" -ARK_VER="4.0.0-dev.2" +SUN_VER="5.0.0" +CV_VER="5.0.0" +CVS_VER="5.0.0" +IDA_VER="5.0.0" +IDAS_VER="4.0.0" +KIN_VER="5.0.0" +ARK_VER="4.0.0" #--------------------------------------------------------- # Test if the script is executed from within its directory diff --git a/scripts/updateVersion.sh b/scripts/updateVersion.sh index bff453f58d..f83ec8601c 100755 --- a/scripts/updateVersion.sh +++ b/scripts/updateVersion.sh @@ -21,7 +21,7 @@ sun_major=${1:-5} sun_minor=${2:-0} sun_patch=${3:-0} -sun_label=${4:-dev.2} +sun_label=${4:""} month=${5:-$(date +"%b")} year=${6:-$(date +"%Y")} diff --git a/src/arkode/README.md b/src/arkode/README.md index 7e736ad961..f4885251a7 100644 --- a/src/arkode/README.md +++ b/src/arkode/README.md @@ -1,8 +1,10 @@ # ARKode -### Version 4.0.0-dev.2 (Sep 2019) +### Version 4.0.0 (Oct 2019) -**Daniel R. Reynolds - Department of Mathematics, SMU** +**Daniel R. Reynolds and Jean M. Sexton + Department of Mathematics, SMU + David J. Gardner, Alan C. Hindmarsh, and Carol S. Woodward + Center for Applied Scientific Computing, LLNL** ARKode is a package for the solution of stiff, nonstiff, and multirate ordinary differential equation (ODE) systems (initial value problems) given in linearly @@ -46,8 +48,8 @@ the "SUNDIALS Release History" appendix of the ARKode User Guide. ## References * D. R. Reynolds, D. J. Gardner, A. C. Hindmarsh, C. S. Woodward, and - J. M. Sexton, "User Documentation for ARKode v4.0.0-dev.2," LLNL technical report - LLNL-SM-668082, Sep 2019. + J. M. Sexton, "User Documentation for ARKode v4.0.0," LLNL technical report + LLNL-SM-668082, Oct 2019. -* D. R. Reynolds, "Example Programs for ARKode v4.0.0-dev.2," Technical Report, - Southern Methodist University Center for Scientific Computation, Sep 2019. +* D. R. Reynolds, "Example Programs for ARKode v4.0.0," Technical Report, + Southern Methodist University Center for Scientific Computation, Oct 2019. diff --git a/src/cvode/README.md b/src/cvode/README.md index ffb4b7aa48..bf80105ee0 100644 --- a/src/cvode/README.md +++ b/src/cvode/README.md @@ -1,5 +1,5 @@ # CVODE -### Version 5.0.0-dev.2 (Sep 2019) +### Version 5.0.0 (Oct 2019) **Alan C. Hindmarsh and Radu Serban Center for Applied Scientific Computing, LLNL** @@ -45,11 +45,11 @@ the "SUNDIALS Release History" appendix of the CVODE User Guide. ## References -* A. C. Hindmarsh and R. Serban, "User Documentation for CVODE v5.0.0-dev.2," - LLNL technical report UCRL-SM-208108, Sep 2019. +* A. C. Hindmarsh and R. Serban, "User Documentation for CVODE v5.0.0," + LLNL technical report UCRL-SM-208108, Oct 2019. -* A. C. Hindmarsh and R. Serban, "Example Programs for CVODE v5.0.0-dev.2," - LLNL technical report UCRL-SM-208110, Sep 2019. +* A. C. Hindmarsh and R. Serban, "Example Programs for CVODE v5.0.0," + LLNL technical report UCRL-SM-208110, Oct 2019. * S.D. Cohen and A.C. Hindmarsh, "CVODE, a Stiff/nonstiff ODE Solver in C," Computers in Physics, 10(2), pp. 138-143, 1996. diff --git a/src/cvodes/README.md b/src/cvodes/README.md index 30f7ff5720..8e21be45d9 100644 --- a/src/cvodes/README.md +++ b/src/cvodes/README.md @@ -1,5 +1,5 @@ # CVODES -### Version 5.0.0-dev.2 (Sep 2019) +### Version 5.0.0 (Oct 2019) **Alan C. Hindmarsh and Radu Serban Center for Applied Scientific Computing, LLNL** @@ -41,11 +41,11 @@ the "SUNDIALS Release History" appendix of the CVODES User Guide. ## References -* A. C. Hindmarsh and R. Serban, "User Documentation for CVODES v5.0.0-dev.2," - LLNL technical report UCRL-SM-208111, Sep 2019. +* A. C. Hindmarsh and R. Serban, "User Documentation for CVODES v5.0.0," + LLNL technical report UCRL-SM-208111, Oct 2019. -* A. C. Hindmarsh and R. Serban, "Example Programs for CVODES v5.0.0-dev.2," - LLNL technical report UCRL-SM-208115, Sep 2019. +* A. C. Hindmarsh and R. Serban, "Example Programs for CVODES v5.0.0," + LLNL technical report UCRL-SM-208115, Oct 2019. * R. Serban and A. C. Hindmarsh, "CVODES: the Sensitivity-Enabled ODE solver in SUNDIALS," Proceedings of IDETC/CIE 2005, Sept. 2005, diff --git a/src/ida/README.md b/src/ida/README.md index 069beb190f..41992bc09d 100644 --- a/src/ida/README.md +++ b/src/ida/README.md @@ -1,5 +1,5 @@ # IDA -### Version 5.0.0-dev.2 (Sep 2019) +### Version 5.0.0 (Oct 2019) **Alan C. Hindmarsh and Radu Serban Center for Applied Scientific Computing, LLNL** @@ -44,11 +44,11 @@ the "SUNDIALS Release History" appendix of the IDA User Guide. ## References -* A. C. Hindmarsh, R. Serban, and A. Collier, "User Documentation for IDA v5.0.0-dev.2," - LLNL technical report UCRL-SM-208112, Sep 2019. +* A. C. Hindmarsh, R. Serban, and A. Collier, "User Documentation for IDA v5.0.0," + LLNL technical report UCRL-SM-208112, Oct 2019. -* A. C. Hindmarsh, R. Serban, and A. Collier, "Example Programs for IDA v5.0.0-dev.2," - LLNL technical report UCRL-SM-208113, Sep 2019. +* A. C. Hindmarsh, R. Serban, and A. Collier, "Example Programs for IDA v5.0.0," + LLNL technical report UCRL-SM-208113, Oct 2019. * A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, "SUNDIALS, Suite of Nonlinear and diff --git a/src/idas/README.md b/src/idas/README.md index 0f75bbf42c..7e50752253 100644 --- a/src/idas/README.md +++ b/src/idas/README.md @@ -1,5 +1,5 @@ # IDAS -### Version 4.0.0-dev.2 (Sep 2019) +### Version 4.0.0 (Oct 2019) **Radu Serban Center for Applied Scientific Computing, LLNL** @@ -40,11 +40,11 @@ the "SUNDIALS Release History" appendix of the IDAS User Guide. ## References -* R. Serban, C. Petra,and A. C. Hindmarsh, "User Documentation for IDAS v4.0.0-dev.2," - LLNL technical report UCRL-SM-234051, Sep 2019. +* R. Serban, C. Petra,and A. C. Hindmarsh, "User Documentation for IDAS v4.0.0," + LLNL technical report UCRL-SM-234051, Oct 2019. -* R. Serban and A.C. Hindmarsh, "Example Programs for IDAS v4.0.0-dev.2," - LLNL technical report LLNL-TR-437091, Sep 2019. +* R. Serban and A.C. Hindmarsh, "Example Programs for IDAS v4.0.0," + LLNL technical report LLNL-TR-437091, Oct 2019. * A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, "SUNDIALS, Suite of Nonlinear and diff --git a/src/kinsol/README.md b/src/kinsol/README.md index f92680d08e..38de37010a 100644 --- a/src/kinsol/README.md +++ b/src/kinsol/README.md @@ -1,5 +1,5 @@ # KINSOL -### Version 5.0.0-dev.2 (Sep 2019) +### Version 5.0.0 (Oct 2019) **Aaron Collier, Alan C. Hindmarsh, Radu Serban, and Carol S. Woodward Center for Applied Scientific Computing, LLNL** @@ -45,11 +45,11 @@ the "SUNDIALS Release History" appendix of the KINSOL User Guide. ## References * A. M. Collier, A. C. Hindmarsh, R. Serban, and C. S. Woodward, - "User Documentation for KINSOL v5.0.0-dev.2," LLNL technical report - UCRL-SM-208116, Sep 2019. + "User Documentation for KINSOL v5.0.0," LLNL technical report + UCRL-SM-208116, Oct 2019. -* A. M. Collier and R. Serban, "Example Programs for KINSOL v5.0.0-dev.2," - LLNL technical report UCRL-SM-208114, Sep 2019. +* A. M. Collier and R. Serban, "Example Programs for KINSOL v5.0.0," + LLNL technical report UCRL-SM-208114, Oct 2019. * A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward, "SUNDIALS, Suite of Nonlinear and