SUNStepper basics based on MRIStepInnerStepper #463
Conversation
|
@drreynolds @gardner48 I have made the changes we discussed on Tuesday. Let me know what you think. |
balos1
changed the title
balos1
force-pushed
the
feature/sunstepper
branch
from
a030d57
to
c04f24a
Compare
|
After some more thought and discussion with David on IDA and passing around I'd like to propose the following to make SunStepper self starting (all you need is
where there's a function which can be specified by users (we could have a default that uses |
include/sundials/sundials_stepper.h
Outdated
| sunrealtype* tret); | ||
|
|
||
| typedef SUNErrCode (*SUNStepperFullRhsFn)(SUNStepper stepper, sunrealtype t, | ||
| N_Vector y, N_Vector f, int mode); |
There was a problem hiding this comment.
I'd like to propose removing the mode argument since it's specific to ARKODE and I don't see any general need for it. Currently, the MRI and operator splitting methods always use ARK_FULLRHS_OTHER mode, and the other modes are unused. Any objections/concerns?
| 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 |
There was a problem hiding this comment.
| An :c:type:`SUNStepper` *must* provide implementations of the following | |
| A :c:type:`SUNStepper` *must* provide implementations of the following |
There was a problem hiding this comment.
Are ALL of these functions really "required" for all SUNStepper implementations, or are only some used in various circumstances (in which case a partial implementation could be sufficient)?
There was a problem hiding this comment.
I've updated the docs to indicate they are optional and determined by the "consumer" of the SUNStepper. I'll need to specify the required functionality in the operator splitting PR.
There was a problem hiding this comment.
This looks great.
We may need to be careful with the SUNStepper / MRIStepInnerStepper compatibility since the MRI adaptivity PR #564 adds a couple more routines to the MRIStepInnerStepper, so a "unified" SUNStepper would need those two extra ops to be used in an adaptive MRI sense. I also recommend that in a soon-to-follow release we should consolidate on only the SUNStepper, retaining relevant wrapping as necessary for backwards-compatibility with existing MRIStepInnerStepper objects.
As I mentioned in a comment on the docs, I sincerely doubt that any of the potential "consuming" packages (e.g., SplitStep, ForcingStep, discrete adjoint integration, XBraid, MRIStep) actually require the full set of SUNStepper ops to be implemented. If each consuming package clearly documented their requirements, then all "consumers" could standardize on SUNStepper.
| ARKodeMem ark_mem = (ARKodeMem)arkode_mem; | ||
|
|
||
| SUNErrCode err = SUNStepper_Create(ark_mem->sunctx, stepper); | ||
| if (err != SUN_SUCCESS) { return ARK_SUNSTEPPER_ERR; } |
There was a problem hiding this comment.
Should this invoke arkProcessError?
| SUNStepperFullRhsFn fullrhs; | ||
| SUNStepperResetFn reset; | ||
| SUNStepperSetStopTimeFn setstoptime; | ||
| SUNStepperSetForcingFn setforcing; |
There was a problem hiding this comment.
Note for reviewers: unlike MRIStepInnerStepper, SUNStepper does not include properties for forcing. It defers that to the implementation. This streamlines this struct, removes the need for a forcing "getter," and can reduce storage (saves a N_Vector for ForcingStep over previous version).
| .. _SUNStepper.Description.BaseMethods.SteppingFunctions: | ||
|
|
||
| Stepping Functions | ||
| ^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
Note for reviewers: Unlike MRIStepInnerStepper, the functions in this section are publicly documented. They can be hidden if folks think that's preferable.
| Attaching and Accessing the Content Pointer | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| .. c:function:: SUNErrCode SUNStepper_SetContent(SUNStepper stepper, void *content) |
There was a problem hiding this comment.
Note for reviewers: these functions are new to SUNStepper compared to MRIStepInnerStepper. Since the SUNStepper struct is private, I think this is the proper way to access the last_flag.
| SUNErrCode SUNStepper_SetOneStepFn(SUNStepper stepper, SUNStepperOneStepFn fn); | ||
|
|
||
| SUNDIALS_EXPORT | ||
| SUNErrCode SUNStepper_SetFullRhsFn(SUNStepper stepper, SUNStepperFullRhsFn fn); |
There was a problem hiding this comment.
Note to reviewers: there is no analogous SUNStepper_FullRhs. This is following what MRI does where it was presumably excluded because the full RHS functions are private in ARKODE. I can make a public SUNStepper_FullRhs function if folks want.
| 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 |
There was a problem hiding this comment.
I've updated the docs to indicate they are optional and determined by the "consumer" of the SUNStepper. I'll need to specify the required functionality in the operator splitting PR.
I am opening this PR as a draft to gather feedback. This renames/moves
MRIStepInnerSteppertoSUNStepperso that @Steven-Roberts and I can extend it for other purposes.