From 99800909f4ca778cc86db52b4222cd483b3c969d Mon Sep 17 00:00:00 2001 From: Steven Roberts Date: Wed, 18 Sep 2024 16:22:49 -0700 Subject: [PATCH 1/3] Changelog --- CHANGELOG.md | 5 + .../source/Usage/ARKStep/User_callable.rst | 22 ++ doc/arkode/guide/source/index.rst | 1 + .../source/sunstepper/SUNStepper_links.rst | 14 + doc/arkode/guide/source/sunstepper/index.rst | 44 +++ doc/shared/RecentChanges.rst | 5 + .../sunstepper/SUNStepper_Description.rst | 372 ++++++++++++++++++ .../sunstepper/SUNStepper_Implementing.rst | 55 +++ doc/superbuild/source/index.rst | 1 + .../source/sunstepper/SUNStepper_links.rst | 14 + doc/superbuild/source/sunstepper/index.rst | 44 +++ 11 files changed, 577 insertions(+) create mode 100644 doc/arkode/guide/source/sunstepper/SUNStepper_links.rst create mode 100644 doc/arkode/guide/source/sunstepper/index.rst create mode 100644 doc/shared/sunstepper/SUNStepper_Description.rst create mode 100644 doc/shared/sunstepper/SUNStepper_Implementing.rst create mode 100644 doc/superbuild/source/sunstepper/SUNStepper_links.rst create mode 100644 doc/superbuild/source/sunstepper/index.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index 74abb6520e..d9e79c6914 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ ### New Features and Enhancements +Added the `SUNStepper` base class to represent a generic solution procedure for +IVPs. This is used by the SplittingStep and ForcingStep modules of ARKODE. A +SUNStepper can be created from an ARKstep memory block with the new function +`ARKStepCreateSUNStepper`. + The default value of `CMAKE_CUDA_ARCHITECTURES` is no longer set to `70` and is now determined automatically by CMake. The previous default was only valid for Volta GPUs while the automatically selected value will vary across compilers and diff --git a/doc/arkode/guide/source/Usage/ARKStep/User_callable.rst b/doc/arkode/guide/source/Usage/ARKStep/User_callable.rst index 5a21f7ea15..1aa31d7d4f 100644 --- a/doc/arkode/guide/source/Usage/ARKStep/User_callable.rst +++ b/doc/arkode/guide/source/Usage/ARKStep/User_callable.rst @@ -4400,3 +4400,25 @@ wrap an ARKStep memory block as an :c:type:`MRIStepInnerStepper`. **Example codes:** * ``examples/arkode/CXX_parallel/ark_diffusion_reaction_p.cpp`` + + +.. _ARKStep_CInterface.SUNStepperInterface: + +Interfacing with SUNStepper +--------------------------- + +The utility function :c:func:`ARKStepCreateSUNStepper` can be used to wrap an +ARKStep memory block as a :c:type:`SUNStepper`. + +.. c:function:: int ARKStepCreateSUNStepper(void *inner_arkode_mem, SUNStepper *stepper) + + Wraps an ARKStep memory block as a :c:type:`SUNStepper`. + + **Arguments:** + * *arkode_mem* -- pointer to the ARKStep memory block. + * *stepper* -- the :c:type:`SUNStepper` object. + + **Return value:** + * *ARK_SUCCESS* if successful + * *ARK_MEM_FAIL* if a memory allocation failed + * *ARK_ILL_INPUT* if an argument has an illegal value. diff --git a/doc/arkode/guide/source/index.rst b/doc/arkode/guide/source/index.rst index e809010fd0..edb093b943 100644 --- a/doc/arkode/guide/source/index.rst +++ b/doc/arkode/guide/source/index.rst @@ -65,6 +65,7 @@ with support by the `US Department of Energy `_, sunlinsol/index.rst sunnonlinsol/index.rst sunadaptcontroller/index.rst + sunstepper/index.rst sunmemory/index.rst sundials/Install_link.rst Constants diff --git a/doc/arkode/guide/source/sunstepper/SUNStepper_links.rst b/doc/arkode/guide/source/sunstepper/SUNStepper_links.rst new file mode 100644 index 0000000000..938c5f5d9d --- /dev/null +++ b/doc/arkode/guide/source/sunstepper/SUNStepper_links.rst @@ -0,0 +1,14 @@ +.. ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. include:: ../../../../shared/sunstepper/SUNStepper_Description.rst +.. include:: ../../../../shared/sunstepper/SUNStepper_Implementing.rst diff --git a/doc/arkode/guide/source/sunstepper/index.rst b/doc/arkode/guide/source/sunstepper/index.rst new file mode 100644 index 0000000000..888df06701 --- /dev/null +++ b/doc/arkode/guide/source/sunstepper/index.rst @@ -0,0 +1,44 @@ +.. ---------------------------------------------------------------- + Programmer(s): Steven B. Roberts @ LLNL + ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. _SUNStepper: + +##################################### +Stepper Data Structure +##################################### + +This section presents the :c:type:`SUNStepper` base class which represents a +generic solution procedure for IVPs of the form + +.. math:: + \dot{v}(t) = f(t, v) + r(t), \qquad v(t_0) = v_0, + :label: SUNStepper_IVP + +on an interval :math:`t \in [t_0, t_f]`. The forcing term, :math:`r_i(t)`, is +given by + +.. math:: + r(t) = \sum_{k = 0}^{n_{\text{forcing}}} + \frac{t - t_{\text{shift}}}{t_{\text{scale}}} \widehat{f}_k. + :label: SUNStepper_forcing + +:c:type:`SUNStepper` provides an abstraction over SUNDIALS integrators, custom +integrators, exact solution procedures, or other approaches for solving +:eq:`SUNStepper_IVP`. These are used, for example, in operator splitting and +forcing methods to solve inner IVPs in a flexible way. + +.. toctree:: + :maxdepth: 1 + + SUNStepper_links.rst diff --git a/doc/shared/RecentChanges.rst b/doc/shared/RecentChanges.rst index fc2568901e..fdd4beeb3c 100644 --- a/doc/shared/RecentChanges.rst +++ b/doc/shared/RecentChanges.rst @@ -2,6 +2,11 @@ **New Features and Enhancements** +Added the :c:type:`SUNStepper` base class to represent a generic solution +procedure for IVPs. This is used by the SplittingStep and ForcingStep modules of +ARKODE. A SUNStepper can be created from an ARKstep memory block with the new +function :c:func:`ARKStepCreateSUNStepper`. + The default value of :cmakeop:`CMAKE_CUDA_ARCHITECTURES` is no longer set to ``70`` and is now determined automatically by CMake. The previous default was only valid for Volta GPUs while the automatically selected value will vary diff --git a/doc/shared/sunstepper/SUNStepper_Description.rst b/doc/shared/sunstepper/SUNStepper_Description.rst new file mode 100644 index 0000000000..eaeae2efc7 --- /dev/null +++ b/doc/shared/sunstepper/SUNStepper_Description.rst @@ -0,0 +1,372 @@ +.. ---------------------------------------------------------------- + Programmer(s): David J. Gardner @ LLNL + Steven B. Roberts @LLNL + ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. _SUNStepper.Description: + +The SUNStepper API +================== + +.. versionadded:: x.y.z + +As with other SUNDIALS classes, the :c:type:`SUNStepper` abstract base class is +implemented using a C structure containing a ``content`` pointer to the derived +class member data and a structure of function pointers the derived class +implementations of the virtual methods. + +.. c:type:: SUNStepper + + An object for solving the IVP :eq:`SUNStepper_IVP`. + + The actual definition of the ``SUNStepper`` structure is kept private to + allow for the object internals to change without impacting user code. The + following sections describe the base class methods and the virtual methods + that a must be provided by a derived class. + +.. _SUNStepper.Description.BaseMethods: + +Base Class Methods +------------------ + +This section describes methods provided by the :c:type:`SUNStepper` abstract +base class that aid the user in implementing derived classes. This includes +functions for creating and destroying a generic base class object, attaching and +retrieving the derived class ``content`` pointer, setting function pointers to +derived class method implementations, and accessing base class data e.g., for +computing the forcing term :eq:`SUNStepper_forcing`. + +.. _SUNStepper.Description.BaseMethods.CreateDestroy: + +Creating and Destroying an Object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. c:function:: SUNErrCode SUNStepper_Create(SUNContext sunctx, SUNStepper *stepper) + + This function creates a :c:type:`SUNStepper` object to which a user should + attach the member data (content) pointer and method function pointers. + + **Arguments:** + * ``sunctx`` -- the SUNDIALS simulation context. + * ``stepper`` -- a pointer to a stepper object. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* create an instance of the base class */ + SUNStepper stepper = NULL; + err = SUNStepper_Create(&stepper); + + .. note:: + + See :numref:`SUNStepper.Description.BaseMethods.Content` and + :numref:`SUNStepper.Description.BaseMethods.AttachFunctions` + for details on how to attach member data and method function pointers. + + +.. c:function:: SUNErrCode SUNStepper_Destroy(SUNStepper *stepper) + + This function destroys a :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a pointer to a stepper object. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* destroy an instance of the base class */ + err = SUNStepper_Destroy(&stepper); + + .. note:: + + This function only frees memory allocated within the base class and the + base class structure itself. The user is responsible for freeing any + memory allocated for the member data (content). + +.. _SUNStepper.Description.BaseMethods.Content: + +Attaching and Accessing the Content Pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. c:function:: SUNErrCode SUNStepper_SetContent(SUNStepper stepper, void *content) + + This function attaches a member data (content) pointer to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *content* -- a pointer to the stepper member data. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper content pointer */ + MyStepperContent my_object_data; + err = SUNStepper_SetContent(stepper, &my_object_data); + + +.. c:function:: SUNErrCode SUNStepper_GetContent(SUNStepper stepper, void **content) + + This function retrieves the member data (content) pointer from a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *content* -- a pointer to set to the stepper member data pointer. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* get the stepper content pointer */ + void *content; + MyStepperContent *my_object_data; + + err = SUNStepper_GetContent(stepper, &content); + my_object_data = (MyStepperContent*) content; + + +.. _SUNStepper.Description.BaseMethods.AttachFunctions: + +Setting Member Functions +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. c:function:: SUNErrCode SUNStepper_SetEvolveFn(SUNStepper stepper, SUNStepperEvolveFn fn) + + This function attaches a :c:type:`SUNStepperEvolveFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperEvolveFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper evolve function */ + err = SUNStepper_SetEvolveFn(stepper, MyEvolve); + + +.. c:function:: SUNErrCode SUNStepper_SetFullRhsFn(SUNStepper stepper, SUNStepperFullRhsFn fn) + + This function attaches a :c:type:`SUNStepperFullRhsFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperFullRhsFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper full right-hand side function */ + err = SUNStepper_SetFullRhsFn(stepper, MyFullRHS); + + +.. c:function:: SUNErrCode SUNStepper_SetResetFn(SUNStepper stepper, SUNStepperResetFn fn) + + This function attaches a :c:type:`SUNStepperResetFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperResetFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper reset function */ + err = SUNStepper_SetResetFn(stepper, MyReset); + + +.. _SUNStepper.Description.BaseMethods.Forcing: + +Applying and Accessing Forcing Data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When integrating the ODE :eq:`SUNStepper_IVP` the :c:type:`SUNStepper` is +responsible for evaluating ODE right-hand side function :math:`f(t, v)` as well +as computing and applying the forcing term :eq:`SUNStepper_forcing` to obtain +the full right-hand side of the ODE :eq:`SUNStepper_IVP`. The functions in this +section can be used to either apply the forcing or access the data necessary to +construct the forcing polynomial. + + +.. c:function:: SUNErrCode SUNStepper_AddForcing(SUNStepper stepper, sunrealtype t, N_Vector f) + + This function computes the forcing term :eq:`SUNStepper_forcing` at the input + time *t* and adds it to input vector *f*, i.e., the right-hand side vector. + + **Arguments:** + * *stepper* -- a stepper object. + * *t* -- the time at which the forcing should be evaluated. + * *f* -- the vector to which the forcing should be applied. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* compute the forcing term and add it the fast RHS vector */ + err = SUNStepper_AddForcing(stepper, t, f); + + +.. c:function:: SUNErrCode SUNStepper_GetForcingData(SUNStepper stepper, sunrealtype *tshift, sunrealtype *tscale, N_Vector **forcing, int *nforcing) + + This function provides access to data necessary to compute the forcing term + :eq:`SUNStepper_forcing`. This includes the shift and scaling factors for the + normalized time :math:`\frac{t - t_{\text{shift}}}{t_{\text{scale}}}` and the + array of polynomial coefficient vectors :math:`\widehat{f}_k`. + + **Arguments:** + * *stepper* -- a stepper object. + * *tshift* -- the time shift to apply to the current time when computing + the forcing, :math:`t_{\text{shift}}`. + * *tscale* -- the time scaling to apply to the current time when computing + the forcing, :math:`t_{\text{scale}}`. + * *forcing* -- a pointer to an array of forcing vectors, + :math:`\widehat{f}_k`. + * *nforcing* -- the number of forcing vectors, :math:`n_{\text{forcing}}`. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + SUNErrCode err + int k; + int nforcing_vecs; /* number of forcing vectors */ + double tshift, tscale; /* time normalization values */ + double tau; /* normalized time */ + double tau_k; /* tau raised to the power k */ + N_Vector *forcing_vecs; /* array of forcing vectors */ + + /* get the forcing data from the stepper */ + err = SUNStepper_GetForcingData(stepper, &tshift, &tscale, + &forcing_vecs, &nforcing_vecs); + + /* compute the normalized time, initialize tau^k */ + tau = (t - tshift) / tscale; + tau_k = 1.0; + + /* compute the polynomial forcing terms and add them to fast RHS vector */ + for (k = 0; k < nforcing_vecs; k++) + { + N_VLinearSum(1.0, f_fast, tau_k, forcing_vecs[k], f_fast); + tau_k *= tau; + } + + +.. _SUNStepper.Description.ImplMethods: + +Implementation Specific Methods +------------------------------- + +This section describes the required and optional virtual methods defined by the +:c:type:`SUNStepper` abstract base class. + +Required Member Functions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +An :c:type:`SUNStepper` *must* provide implementations of the following +member functions: + + +.. c:type:: SUNErrCode (*SUNStepperEvolveFn)(SUNStepper stepper, sunrealtype t0, sunrealtype tout, N_Vector v) + + This function advances the state vector *v* for the ODE system from time *t0* + to time *tout*. + + **Arguments:** + * *stepper* -- the stepper object. + * *t0* -- the initial time for the integration. + * *tout* -- the final time for the integration. + * *v* -- on input the state at time *t0* and, on output, the state at time + *tout*. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + +.. c:type:: SUNErrCode (*SUNStepperResetFn)(SUNStepper stepper, sunrealtype tR, N_Vector vR) + + This function resets the stepper state to the provided independent variable + value and dependent variable vector. + + **Arguments:** + * *stepper* -- the stepper object. + * *tR* -- the value of the independent variable :math:`t_R`. + * *vR* -- the value of the dependent variable vector :math:`v(t_R)`. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + +Optional Member Functions +^^^^^^^^^^^^^^^^^^^^^^^^^ + +An :c:type:`SUNStepper` *may* provide implementations of any of the following +member functions: + +.. c:type:: SUNErrCode (*SUNStepperFullRhsFn)(SUNStepper stepper, sunrealtype t, N_Vector v, N_Vector f, int mode) + + This function computes the full right-hand side function of the ODE, + :math:`f(t, v)` in :eq:`SUNStepper_IVP` for a given value of the independent + variable *t* and state vector *y*. + + **Arguments:** + * *stepper* -- the stepper object. + * *t* -- the current value of the independent variable. + * *v* -- the current value of the dependent variable vector. + * *f* -- the output vector for the ODE right-hand side, :math:`f(t, v)`, + in :eq:`SUNStepper_IVP`. + * *mode* -- a flag indicating the purpose for which the right-hand side + function evaluation is called. + + * ``ARK_FULLRHS_START`` -- called at the beginning of the simulation + * ``ARK_FULLRHS_END`` -- called at the end of a successful step + * ``ARK_FULLRHS_OTHER`` -- called elsewhere e.g., for dense output + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. diff --git a/doc/shared/sunstepper/SUNStepper_Implementing.rst b/doc/shared/sunstepper/SUNStepper_Implementing.rst new file mode 100644 index 0000000000..500e41d927 --- /dev/null +++ b/doc/shared/sunstepper/SUNStepper_Implementing.rst @@ -0,0 +1,55 @@ +.. ---------------------------------------------------------------- + Programmer(s): David J. Gardner @ LLNL + Steven B. Roberts @ LLNL + ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. _SUNStepper.Implementing: + +Implementing a SunStepper +========================= + +To create a SUNStepper implementation: + +#. Define the stepper-specific content. + + This is typically a user-defined structure in C codes, a user-defined class + or structure in C++ codes, or a user-defined module in Fortran codes. This + content should hold any data necessary to perform the operations defined by + the :c:type:`SUNStepper` member functions. + +#. Define implementations of the required member functions (see + :numref:`SUNStepper.Description.ImplMethods`). + + These are typically user-defined functions in C, member functions of the + user-defined structure or class in C++, or functions contained in the + user-defined module in Fortran. + + Note that all member functions are passed the :c:type:`SUNStepper` object and + the stepper-specific content can, if necessary, be retrieved using + :c:func:`SUNStepper_GetContent`. + +#. In the user code, before creating the outer memory structure that uses the + :c:type:`SUNStepper`, e.g., with :c:func:`SplittingStepCreate` or + :c:func:`ForcingStepCreate`, do the following: + + #. Create a :c:type:`SUNStepper` object with :c:func:`SUNStepper_Create`. + + #. Attach a pointer to the stepper content to the :c:type:`SUNStepper` object + with :c:func:`SUNStepper_SetContent` if necessary, e.g., when the content + is a C structure. + + #. Attach the member function implementations using the functions described + in :numref:`SUNStepper.Description.BaseMethods.AttachFunctions`. + +#. Attach the :c:type:`SUNStepper` object to the outer memory structure, e.g., + with :c:func:`SplittingStepCreate` or :c:func:`ForcingStepCreate`. diff --git a/doc/superbuild/source/index.rst b/doc/superbuild/source/index.rst index e61162c884..d597a82a0c 100644 --- a/doc/superbuild/source/index.rst +++ b/doc/superbuild/source/index.rst @@ -174,6 +174,7 @@ SUNDIALS License and Notices sunlinsol/index.rst sunnonlinsol/index.rst sunadaptcontroller/index.rst + sunstepper/index.rst sunmemory/index.rst History_link.rst Changelog_link.rst diff --git a/doc/superbuild/source/sunstepper/SUNStepper_links.rst b/doc/superbuild/source/sunstepper/SUNStepper_links.rst new file mode 100644 index 0000000000..925278111c --- /dev/null +++ b/doc/superbuild/source/sunstepper/SUNStepper_links.rst @@ -0,0 +1,14 @@ +.. ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. include:: ../../../shared/sunstepper/SUNStepper_Description.rst +.. include:: ../../../shared/sunstepper/SUNStepper_Implementing.rst diff --git a/doc/superbuild/source/sunstepper/index.rst b/doc/superbuild/source/sunstepper/index.rst new file mode 100644 index 0000000000..b13a03f4d2 --- /dev/null +++ b/doc/superbuild/source/sunstepper/index.rst @@ -0,0 +1,44 @@ +.. ---------------------------------------------------------------- + Programmer(s): Steven B. Roberts @ LLNL + ---------------------------------------------------------------- + SUNDIALS Copyright Start + Copyright (c) 2002-2024, Lawrence Livermore National Security + and Southern Methodist University. + All rights reserved. + + See the top-level LICENSE and NOTICE files for details. + + SPDX-License-Identifier: BSD-3-Clause + SUNDIALS Copyright End + ---------------------------------------------------------------- + +.. _SUNStepper: + +##################################### +Stepper Data Structure +##################################### + +This section presents the :c:type:`SUNStepper` base class which represents a +generic solution procedure for IVPs of the form + +.. math:: + \dot{v}(t) = f(t, v) + r(t), \qquad v(t_0) = v_0, + :label: SUNStepper_IVP + +on an interval :math:`t \in [t_0, t_f]`. The forcing term, :math:`r_i(t)`, is +given by + +.. math:: + r(t) = \sum_{k = 0}^{n_{\text{forcing}}} + \frac{t - t_{\text{shift}}}{t_{\text{scale}}} \widehat{f}_k. + :label: SUNStepper_forcing + +:c:type:`SUNStepper` provides an abstraction over SUNDIALS integrators, custom +integrators, exact solution procedures, or other approaches for solving +:eq:`SUNStepper_IVP`. These are used, for example, in operator splitting and +forcing methods to solve inner IVPs in a flexible way. + +.. toctree:: + :maxdepth: 1 + + SUNStepper_links.rst From d3ca3b8ad9034f71e2658303aaf990c2363e645c Mon Sep 17 00:00:00 2001 From: Steven Roberts Date: Wed, 18 Sep 2024 17:22:02 -0700 Subject: [PATCH 2/3] Doc fixes --- .../sunstepper/SUNStepper_Description.rst | 106 +++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) diff --git a/doc/shared/sunstepper/SUNStepper_Description.rst b/doc/shared/sunstepper/SUNStepper_Description.rst index eaeae2efc7..11cbe6cbe2 100644 --- a/doc/shared/sunstepper/SUNStepper_Description.rst +++ b/doc/shared/sunstepper/SUNStepper_Description.rst @@ -175,6 +175,44 @@ Setting Member Functions /* set the stepper evolve function */ err = SUNStepper_SetEvolveFn(stepper, MyEvolve); +.. c:function:: SUNErrCode SUNStepper_SetOneStepFn(SUNStepper stepper, SUNStepperOneStepFn fn) + + This function attaches a :c:type:`SUNStepperOneStepFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperOneStepFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper one step function */ + err = SUNStepper_SetOneStepFn(stepper, MyOneStep); + +.. c:function:: SUNErrCode SUNStepper_SetTryStepFn(SUNStepper stepper, SUNStepperTryStepFn fn) + + This function attaches a :c:type:`SUNStepperTryStepFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperTryStepFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper try step function */ + err = SUNStepper_SetTryStepFn(stepper, MyTryStep); + .. c:function:: SUNErrCode SUNStepper_SetFullRhsFn(SUNStepper stepper, SUNStepperFullRhsFn fn) @@ -216,6 +254,26 @@ Setting Member Functions err = SUNStepper_SetResetFn(stepper, MyReset); +.. c:function:: SUNErrCode SUNStepper_SetStopTimeFn(SUNStepper stepper, SUNStepperSetStopTimeFn fn) + + This function attaches a :c:type:`SUNStepperSetStopTimeFn` function to a + :c:type:`SUNStepper` object. + + **Arguments:** + * *stepper* -- a stepper object. + * *fn* -- the :c:type:`SUNStepperSetStopTimeFn` function to attach. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + **Example usage:** + + .. code-block:: C + + /* set the stepper reset function */ + err = SUNStepper_SetStopTimeFn(stepper, MyStopTime); + + .. _SUNStepper.Description.BaseMethods.Forcing: Applying and Accessing Forcing Data @@ -313,7 +371,7 @@ An :c:type:`SUNStepper` *must* provide implementations of the following member functions: -.. c:type:: SUNErrCode (*SUNStepperEvolveFn)(SUNStepper stepper, sunrealtype t0, sunrealtype tout, N_Vector v) +.. c:type:: SUNErrCode (*SUNStepperEvolveFn)(SUNStepper stepper, sunrealtype t0, sunrealtype tout, N_Vector v, sunrealtype* tret, int* stop_reason) This function advances the state vector *v* for the ODE system from time *t0* to time *tout*. @@ -324,6 +382,39 @@ member functions: * *tout* -- the final time for the integration. * *v* -- on input the state at time *t0* and, on output, the state at time *tout*. + * *tret* -- the final time corresponding to the output value *v*. + * *stop_reason* -- TODO + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + +.. c:type:: SUNErrCode (*SUNStepperOneStepFn)(SUNStepper stepper, sunrealtype t0, sunrealtype tout, N_Vector v, sunrealtype* tret, int* stop_reason) + + TODO + + **Arguments:** + * *stepper* -- the stepper object. + * *t0* -- the initial time for the integration. + * *tout* -- the final time for the integration. + * *v* -- on input the state at time *t0* and, on output, the state at time + *tout*. + * *tret* -- the final time corresponding to the output value *v*. + * *stop_reason* -- TODO + + +.. c:type:: SUNErrCode (*SUNStepperTryStepFn)(SUNStepper stepper, sunrealtype t0, sunrealtype tout, N_Vector v, sunrealtype* tret, int* stop_reason) + + TODO + + **Arguments:** + * *stepper* -- the stepper object. + * *t0* -- the initial time for the integration. + * *tout* -- the final time for the integration. + * *v* -- on input the state at time *t0* and, on output, the state at time + *tout*. + * *tret* -- the final time corresponding to the output value *v*. + * *stop_reason* -- TODO **Return value:** * A :c:type:`SUNErrCode` indicating success or failure. @@ -343,6 +434,19 @@ member functions: * A :c:type:`SUNErrCode` indicating success or failure. +.. c:type:: SUNErrCode (*SUNStepperSetStopTimeFn)(SUNStepper stepper, sunrealtype tstop) + + This function specifies the value of the independent variable :math:`t` past + which the solution is not to proceed. + + **Arguments:** + * *stepper* -- the stepper object. + * *tstop* -- stopping time for the stepper. + + **Return value:** + * A :c:type:`SUNErrCode` indicating success or failure. + + Optional Member Functions ^^^^^^^^^^^^^^^^^^^^^^^^^ From 1672e09039758bca4bd9b77e96e15a64193249d1 Mon Sep 17 00:00:00 2001 From: Steven Roberts Date: Wed, 18 Sep 2024 17:26:37 -0700 Subject: [PATCH 3/3] Reorder implementation specific methods --- .../sunstepper/SUNStepper_Description.rst | 59 ++++++++----------- 1 file changed, 25 insertions(+), 34 deletions(-) diff --git a/doc/shared/sunstepper/SUNStepper_Description.rst b/doc/shared/sunstepper/SUNStepper_Description.rst index 11cbe6cbe2..26ca06a759 100644 --- a/doc/shared/sunstepper/SUNStepper_Description.rst +++ b/doc/shared/sunstepper/SUNStepper_Description.rst @@ -361,11 +361,8 @@ construct the forcing polynomial. Implementation Specific Methods ------------------------------- -This section describes the required and optional virtual methods defined by the -:c:type:`SUNStepper` abstract base class. - -Required Member Functions -^^^^^^^^^^^^^^^^^^^^^^^^^ +This section describes the virtual methods defined by the :c:type:`SUNStepper` +abstract base class. An :c:type:`SUNStepper` *must* provide implementations of the following member functions: @@ -420,57 +417,51 @@ member functions: * A :c:type:`SUNErrCode` indicating success or failure. -.. c:type:: SUNErrCode (*SUNStepperResetFn)(SUNStepper stepper, sunrealtype tR, N_Vector vR) +.. c:type:: SUNErrCode (*SUNStepperFullRhsFn)(SUNStepper stepper, sunrealtype t, N_Vector v, N_Vector f, int mode) - This function resets the stepper state to the provided independent variable - value and dependent variable vector. + This function computes the full right-hand side function of the ODE, + :math:`f(t, v)` in :eq:`SUNStepper_IVP` for a given value of the independent + variable *t* and state vector *y*. **Arguments:** * *stepper* -- the stepper object. - * *tR* -- the value of the independent variable :math:`t_R`. - * *vR* -- the value of the dependent variable vector :math:`v(t_R)`. + * *t* -- the current value of the independent variable. + * *v* -- the current value of the dependent variable vector. + * *f* -- the output vector for the ODE right-hand side, :math:`f(t, v)`, + in :eq:`SUNStepper_IVP`. + * *mode* -- a flag indicating the purpose for which the right-hand side + function evaluation is called. + + * ``ARK_FULLRHS_START`` -- called at the beginning of the simulation + * ``ARK_FULLRHS_END`` -- called at the end of a successful step + * ``ARK_FULLRHS_OTHER`` -- called elsewhere e.g., for dense output **Return value:** * A :c:type:`SUNErrCode` indicating success or failure. -.. c:type:: SUNErrCode (*SUNStepperSetStopTimeFn)(SUNStepper stepper, sunrealtype tstop) +.. c:type:: SUNErrCode (*SUNStepperResetFn)(SUNStepper stepper, sunrealtype tR, N_Vector vR) - This function specifies the value of the independent variable :math:`t` past - which the solution is not to proceed. + This function resets the stepper state to the provided independent variable + value and dependent variable vector. **Arguments:** * *stepper* -- the stepper object. - * *tstop* -- stopping time for the stepper. + * *tR* -- the value of the independent variable :math:`t_R`. + * *vR* -- the value of the dependent variable vector :math:`v(t_R)`. **Return value:** * A :c:type:`SUNErrCode` indicating success or failure. -Optional Member Functions -^^^^^^^^^^^^^^^^^^^^^^^^^ - -An :c:type:`SUNStepper` *may* provide implementations of any of the following -member functions: - -.. c:type:: SUNErrCode (*SUNStepperFullRhsFn)(SUNStepper stepper, sunrealtype t, N_Vector v, N_Vector f, int mode) +.. c:type:: SUNErrCode (*SUNStepperSetStopTimeFn)(SUNStepper stepper, sunrealtype tstop) - This function computes the full right-hand side function of the ODE, - :math:`f(t, v)` in :eq:`SUNStepper_IVP` for a given value of the independent - variable *t* and state vector *y*. + This function specifies the value of the independent variable :math:`t` past + which the solution is not to proceed. **Arguments:** * *stepper* -- the stepper object. - * *t* -- the current value of the independent variable. - * *v* -- the current value of the dependent variable vector. - * *f* -- the output vector for the ODE right-hand side, :math:`f(t, v)`, - in :eq:`SUNStepper_IVP`. - * *mode* -- a flag indicating the purpose for which the right-hand side - function evaluation is called. - - * ``ARK_FULLRHS_START`` -- called at the beginning of the simulation - * ``ARK_FULLRHS_END`` -- called at the end of a successful step - * ``ARK_FULLRHS_OTHER`` -- called elsewhere e.g., for dense output + * *tstop* -- stopping time for the stepper. **Return value:** * A :c:type:`SUNErrCode` indicating success or failure.