Skip to content

Commit

Permalink
tstop-copy (#292)
Browse files Browse the repository at this point in the history 
Changed default 'tstop' behavior of ARKODE and CVODE(S) to copy the
internal solution instead of performing interpolation.

---------

Co-authored-by: Cody Balos <[email protected]>
  • Loading branch information
@drreynolds @balos1
drreynolds and balos1 authored Jul 6, 2023
1 parent 008d69c commit 086b5d6
Show file tree
Hide file tree
Showing 26 changed files with 348 additions and 124 deletions.
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ Updated the F2003 utility routines `SUNDIALSFileOpen` and `SUNDIALSFileClose`
to support user specification of `stdout` and `stderr` strings for the output
file names.

Updated CVODE, CVODES and ARKODE default behavior when returning the solution when
the internal time has reached a user-specified stop time. Previously, the output
solution was interpolated to the value of `tstop`; the default is now to copy the
internal solution vector. Users who wish to revert to interpolation may call a new
routine `CVodeSetInterpolateStopTime`, `ARKStepSetInterpolateStopTime`,
`ERKStepSetInterpolateStopTime`, or `MRIStepSetInterpolateStopTime`.

## Changes to SUNDIALS in release 6.5.1

Added the functions `ARKStepClearStopTime`, `ERKStepClearStopTime`,
Expand Down
7 changes: 7 additions & 0 deletions doc/arkode/guide/source/Introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,13 @@ Updated the F2003 utility routines :c:func:`SUNDIALSFileOpen` and :c:func:`SUNDI
to support user specification of ``stdout`` and ``stderr`` strings for the output
file names.

Updated the default ARKODE behavior when returning the solution when
the internal time has reached a user-specified stop time. Previously, the output
solution was interpolated to the value of ``tstop``; the default is now to copy the
internal solution vector. Users who wish to revert to interpolation may call a new
routine :c:func:`ARKStepSetInterpolateStopTime`,
:c:func:`ERKStepSetInterpolateStopTime`, or :c:func:`MRIStepSetInterpolateStopTime`.

Changes in v5.5.1
-----------------

Expand Down
18 changes: 18 additions & 0 deletions doc/arkode/guide/source/Usage/ARKStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -876,6 +876,7 @@ Maximum no. of internal steps before *tout* :c:func:`ARKStepSetMaxNumSteps
Maximum absolute step size :c:func:`ARKStepSetMaxStep` :math:`\infty`
Minimum absolute step size :c:func:`ARKStepSetMinStep` 0.0
Set a value for :math:`t_{stop}` :c:func:`ARKStepSetStopTime` undefined
Interpolate at :math:`t_{stop}` :c:func:`ARKStepSetInterpolateStopTime` ``SUNFALSE``
Disable the stop time :c:func:`ARKStepClearStopTime` N/A
Supply a pointer for user data :c:func:`ARKStepSetUserData` ``NULL``
Maximum no. of ARKStep error test failures :c:func:`ARKStepSetMaxErrTestFails` 7
Expand Down Expand Up @@ -1267,6 +1268,23 @@ Set max number of constraint failures :c:func:`ARKStepSetMaxNumConst
:c:func:`ARKStepClearStopTime`.
.. c:function:: int ARKStepSetInterpolateStopTime(void* arkode_mem, booleantype interp)
Specifies that the output solution should be interpolated when the current
:math:`t` equals the specified ``tstop`` (instead of merely copying the
internal solution :math:`y_n`).
**Arguments:**
* *arkode_mem* -- pointer to the ARKStep memory block.
* *interp* -- flag indicating to use interpolation (1) or copy (0).
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
.. versionadded:: 5.6.0
.. c:function:: int ARKStepClearStopTime(void* arkode_mem)
Disables the stop time set with :c:func:`ARKStepSetStopTime`.
Expand Down
97 changes: 58 additions & 39 deletions doc/arkode/guide/source/Usage/ERKStep_c_interface/User_callable.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -467,45 +467,47 @@ Optional inputs for ERKStep
.. _ARKODE.Usage.ERKStep.ERKStepInputTable:
.. table:: Optional inputs for ERKStep

+----------------------------------------------------+-----------------------------------------+------------------------+
| Optional input | Function name | Default |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Return ERKStep solver parameters to their defaults | :c:func:`ERKStepSetDefaults()` | internal |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Set dense output interpolation type | :c:func:`ERKStepSetInterpolantType()` | ``ARK_INTERP_HERMITE`` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Set dense output polynomial degree | :c:func:`ERKStepSetInterpolantDegree()` | 5 |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Supply a pointer to a diagnostics output file | :c:func:`ERKStepSetDiagnostics()` | ``NULL`` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Supply a pointer to an error output file | :c:func:`ERKStepSetErrFile()` | ``stderr`` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Supply a custom error handler function | :c:func:`ERKStepSetErrHandlerFn()` | internal fn |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Disable time step adaptivity (fixed-step mode) | :c:func:`ERKStepSetFixedStep()` | disabled |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Supply an initial step size to attempt | :c:func:`ERKStepSetInitStep()` | estimated |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Maximum no. of warnings for :math:`t_n+h = t_n` | :c:func:`ERKStepSetMaxHnilWarns()` | 10 |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Maximum no. of internal steps before *tout* | :c:func:`ERKStepSetMaxNumSteps()` | 500 |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Maximum absolute step size | :c:func:`ERKStepSetMaxStep()` | :math:`\infty` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Minimum absolute step size | :c:func:`ERKStepSetMinStep()` | 0.0 |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Set a value for :math:`t_{stop}` | :c:func:`ERKStepSetStopTime()` | undefined |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Disable the stop time | :c:func:`ERKStepClearStopTime` | N/A |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Supply a pointer for user data | :c:func:`ERKStepSetUserData()` | ``NULL`` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Maximum no. of ERKStep error test failures | :c:func:`ERKStepSetMaxErrTestFails()` | 7 |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Set inequality constraints on solution | :c:func:`ERKStepSetConstraints()` | ``NULL`` |
+----------------------------------------------------+-----------------------------------------+------------------------+
| Set max number of constraint failures | :c:func:`ERKStepSetMaxNumConstrFails()` | 10 |
+----------------------------------------------------+-----------------------------------------+------------------------+
+----------------------------------------------------+-------------------------------------------+------------------------+
| Optional input | Function name | Default |
+====================================================+===========================================+========================+
| Return ERKStep solver parameters to their defaults | :c:func:`ERKStepSetDefaults()` | internal |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Set dense output interpolation type | :c:func:`ERKStepSetInterpolantType()` | ``ARK_INTERP_HERMITE`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Set dense output polynomial degree | :c:func:`ERKStepSetInterpolantDegree()` | 5 |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to a diagnostics output file | :c:func:`ERKStepSetDiagnostics()` | ``NULL`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer to an error output file | :c:func:`ERKStepSetErrFile()` | ``stderr`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a custom error handler function | :c:func:`ERKStepSetErrHandlerFn()` | internal fn |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Disable time step adaptivity (fixed-step mode) | :c:func:`ERKStepSetFixedStep()` | disabled |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply an initial step size to attempt | :c:func:`ERKStepSetInitStep()` | estimated |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Maximum no. of warnings for :math:`t_n+h = t_n` | :c:func:`ERKStepSetMaxHnilWarns()` | 10 |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Maximum no. of internal steps before *tout* | :c:func:`ERKStepSetMaxNumSteps()` | 500 |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Maximum absolute step size | :c:func:`ERKStepSetMaxStep()` | :math:`\infty` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Minimum absolute step size | :c:func:`ERKStepSetMinStep()` | 0.0 |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Set a value for :math:`t_{stop}` | :c:func:`ERKStepSetStopTime()` | undefined |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Interpolate at :math:`t_{stop}` | :c:func:`ERKStepInterpolateSetStopTime()` | ``SUNFALSE`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Disable the stop time | :c:func:`ERKStepClearStopTime` | N/A |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Supply a pointer for user data | :c:func:`ERKStepSetUserData()` | ``NULL`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Maximum no. of ERKStep error test failures | :c:func:`ERKStepSetMaxErrTestFails()` | 7 |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Set inequality constraints on solution | :c:func:`ERKStepSetConstraints()` | ``NULL`` |
+----------------------------------------------------+-------------------------------------------+------------------------+
| Set max number of constraint failures | :c:func:`ERKStepSetMaxNumConstrFails()` | 10 |
+----------------------------------------------------+-------------------------------------------+------------------------+



Expand Down Expand Up @@ -886,6 +888,23 @@ Optional inputs for ERKStep
:c:func:`ERKStepClearStopTime`.
.. c:function:: int ERKStepSetInterpolateStopTime(void* arkode_mem, booleantype interp)
Specifies that the output solution should be interpolated when the current
:math:`t` equals the specified ``tstop`` (instead of merely copying the
internal solution :math:`y_n`).
**Arguments:**
* *arkode_mem* -- pointer to the ERKStep memory block.
* *interp* -- flag indicating to use interpolation (1) or copy (0).
**Return value:**
* *ARK_SUCCESS* if successful
* *ARK_MEM_NULL* if the ARKStep memory is ``NULL``
.. versionadded:: 5.6.0
.. c:function:: int ERKStepClearStopTime(void* arkode_mem)
Disables the stop time set with :c:func:`ERKStepSetStopTime`.
Expand Down
Loading

0 comments on commit 086b5d6

Please sign in to comment.