Feature/stageprocessing by drreynolds · Pull Request #813 · llnl/sundials

drreynolds · 2026-01-15T21:09:30Z

This PR adds step preprocessing, failed-step postprocessing, and stage RHS preprocessing to ARKODE.

While existing support for stage and step postprocessing has been useful for some advanced collaborator codes, the lack of symmetry increases challenges when applications must compute auxiliary data (e.g., solving Poisson equations for a potential field) but want do not wish to do this more than absolutely necessary. Additionally, when a step fails our existing step postprocessing is not called, eliminating the possibility for applications to rewind auxiliary data to the previous "accepted" step values.

As with previous postprocessing support, these should be considered advanced/experimental features. As such, they are not advertised in the SUNDIALS documentation

Step preprocessing vs postprocessing

The fundamental difference between these is when the processing routine is called inside the ARKODE time-stepping loop. It is unlikely that a user would use both, but this allows them to more precisely place their processing function.

Stage RHS preprocessing vs stage postprocessing

Stage RHS preprocessing occurs just prior to any set of RHS calls that would use an identical state (e.g., if both explicit and implicit RHS functions would be called on the same input), allowing auxiliary data (e.g., MPI exchange buffers) to be reused in both calls.

On the other hand, stage postprocessing is called just after updating the current stage solution.

Again, it is unlikely that a user would leverage both in the same application, but this allows increased precision over the timings when they are performed.

… step postprocessing

… RHS calls for ImEx methods so that fsi always precedes fse (as with ARKStep)

… RHS functions

drreynolds · 2026-01-20T04:26:51Z

This is the first in a sequence of PRs for ARKODE to support our FES collaborators. Please review this one first. When the stack is complete, we'll do a final PR into develop

…ith the last-accepted-step before starting the step attempt

…some logging

drreynolds · 2026-01-30T03:09:13Z

This PR should be ready to review -- all CI issues resulting from the new release have been resolved.

…r and linear solvers

…tly call the explicit or implicit RHS function

gardner48 · 2026-02-03T06:21:59Z

src/arkode/arkode.c


+      /* fill (tcur,ycur) with the last accepted step solution */
+      ark_mem->tcur = ark_mem->tn;
+      N_VScale(ONE, ark_mem->yn, ark_mem->ycur);


In some cases this copy is redundant (i.e., when taking internal steps in normal mode) because ycur was copied into yn in arkCompleteStep. A few ways we could handle this:

Preprocess yn instead of ycur -- no copy needed, FASL methods will need to re-evaluate the RHS function if the vector is modified (this is true for any of the options, see comments below)

Add a flag like ycur_is_copy_of_yn to signal when the copy is needed -- more bookkeeping, avoids any unnecessary copies but still has extra copies compared to passing yn

Move the copy inside if (ark_mem->PreProcessStep != NULL) -- redundant copies only when a step preprocessing function is attached

Some related issues when preprocessing a step:

Should we call the preprocessing function before any initial step computations (e.g., estimating the initial step size)? This might require more bookkeeping to avoid duplicate preprocessing calls on the same state.

This currently does a copy for each step attempt. If yn was preprocessed rather than ycur, we might be able to call PreProcessStep only on the first attempt and skip it on subsequent step attempts.

As noted above, FSAL methods will need to re-evaluate the RHS if the state is modified so the vales are consistent. I think the best solution here might be to add an output flag to the processing functions to indicate if the state has been modified. For now, this would require adding a new function type and we could deprecate the existing processing function type.

gardner48 · 2026-02-03T06:32:46Z

src/arkode/arkode.c

+    retval = ark_mem->PostProcessStep(ark_mem->tcur, ark_mem->ycur,
+                                      ark_mem->ps_data);
    if (retval != 0) { return (ARK_POSTPROCESS_STEP_FAIL); }
  }


Thinking of the state/RHS consistency for FSAL methods above, this probably needs to move inside the steppers so they can call PostProcessStage or PostProcessesStep as appropriate and remove a potentially redundant processing call

gardner48 · 2026-02-03T06:45:52Z

src/arkode/arkode_arkstep.c

+      }
+
+      /* compute the implicit component */
+      if (step_mem->implicit)


Is there a particular reason to call the implicit RHS first or is this just to make the ordering consistent with what's done in TakeStep?

gardner48 · 2026-02-03T07:03:22Z

src/arkode/arkode_io.c


  /* NULL argument sets default, otherwise set inputs */
-  ark_mem->ProcessStage = ProcessStage;
+  ark_mem->PostProcessStage = ProcessStage;


Suggested change

ark_mem->PostProcessStage = ProcessStage;

ark_mem->PostProcessStage = ProcessStage;

ark_mem->ps_data = ark_mem->user_data;

gardner48 · 2026-02-03T07:04:35Z

src/arkode/arkode_io.c

+  ark_mem = (ARKodeMem)arkode_mem;
+
+  /* NULL argument sets default, otherwise set inputs */
+  ark_mem->PreProcessRHS = PreprocessRHS;


Suggested change

ark_mem->PreProcessRHS = PreprocessRHS;

ark_mem->PreProcessRHS = PreprocessRHS;

ark_mem->ps_data = ark_mem->user_data;

gardner48 · 2026-02-07T02:15:50Z

src/arkode/arkode_sprkstep.c

+        if (retval != 0)
+        {
+          SUNLogInfo(ARK_LOGGER, "end-stages-list",
+                     "status = failed preprocess stage, retval = %i", retval);


Suggested change

"status = failed preprocess stage, retval = %i", retval);

"status = failed preprocess rhs, retval = %i", retval);

gardner48 · 2026-02-07T02:15:59Z

src/arkode/arkode_sprkstep.c

+        if (retval != 0)
+        {
+          SUNLogInfo(ARK_LOGGER, "end-stages-list",
+                     "status = failed preprocess stage, retval = %i", retval);


Suggested change

"status = failed preprocess stage, retval = %i", retval);

"status = failed preprocess rhs, retval = %i", retval);

gardner48 · 2026-02-07T02:22:15Z

src/arkode/arkode.c

                 ark_mem->nst + 1, ark_mem->tn, ark_mem->h);

+      /* fill (tcur,ycur) with the last accepted step solution */
+      ark_mem->tcur = ark_mem->tn;


Note in the change log this fixes an error in the logging output where the time of the first stage would be incorrect when reattempting a step.

gardner48 · 2026-02-07T02:25:14Z

src/arkode/arkode_erkstep.c

The RHS call in TakeStep_Adjoint is missing a PreProcessRHS call, does it need one? Similarly, should there be a PreProcessRHS call before adj_f calls?

gardner48 · 2026-02-07T02:26:32Z

src/arkode/arkode_arkstep.c

The RHS call in TakeStep_ERK_Adjoint is missing a PreProcessRHS call, does it need one? Similarly, is a PreProcessRHS call needed before a adj_fe call?

drreynolds added 14 commits January 9, 2026 11:55

Initial implementation of step/stage preprocessing, as well as failed…

328eea1

… step postprocessing

Regenerated SWIG

9195cda

Ran formatter

876b016

updated pattern for stage preprocessing in ERKStep

0fa2494

updated pattern for stage preprocessing in ARKStep

c8bf4cb

updated pattern for stage preprocessing in SPRKStep

4b24a20

updated pattern for stage preprocessing in SPRKStep

e16f6f2

updated pattern for stage preprocessing in MRIStep; fixed ordering of…

0e0b8d2

… RHS calls for ImEx methods so that fsi always precedes fse (as with ARKStep)

updated pattern for stage preprocessing in LSRKStep

84f706b

Renamed PreProcessStage to PreProcessRHS to clarify its role

98864f9

Regenerated SWIG

f8736ea

Ran formatter

d6d209e

Updated logging output to reflect reordering of explicit and implicit…

801108c

… RHS functions

One more .out file

a76be01

drreynolds requested review from balos1, cswoodward and gardner48 as code owners January 15, 2026 21:09

drreynolds assigned balos1, Steven-Roberts, gardner48 and maggul Jan 15, 2026

drreynolds added the pkg-ARKODE label Jan 15, 2026

drreynolds mentioned this pull request Jan 20, 2026

Removed extraneous yout copy #814

Open

gardner48 added this to the SUNDIALS Next milestone Jan 20, 2026

drreynolds added 5 commits January 26, 2026 08:52

Merge branch 'develop' into feature/stageprocessing

1036279

Updated ARKODE time stepping attempt loop to initialize (tcur,ycur) w…

2f6a251

…ith the last-accepted-step before starting the step attempt

Updated logging output files since tcur was previously inaccurate in …

019702b

…some logging

Updated answers submodule commit

ed6d1f4

Merge branch 'feature/fes-staging' into feature/stageprocessing

66985fa

drreynolds added 5 commits February 3, 2026 10:22

Merge branch 'feature/fes-staging' into feature/stageprocessing

24792e5

Added preprocess-rhs before calls to the implicit RHS in the nonlinea…

4fb8e68

…r and linear solvers

Added some conditionals to only call PreProcessRHS if we will imminen…

c9b0b06

…tly call the explicit or implicit RHS function

Formatting

2920ca4

Fixed parenthesis in conditional

e9af994

gardner48 requested changes Feb 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/stageprocessing#813

Feature/stageprocessing#813
drreynolds wants to merge 24 commits intofeature/fes-stagingfrom
feature/stageprocessing

drreynolds commented Jan 15, 2026

Uh oh!

drreynolds commented Jan 20, 2026

Uh oh!

drreynolds commented Jan 30, 2026

Uh oh!

gardner48 Feb 3, 2026

Uh oh!

gardner48 Feb 3, 2026

Uh oh!

gardner48 Feb 3, 2026

Uh oh!

gardner48 Feb 3, 2026

Uh oh!

gardner48 Feb 3, 2026

Uh oh!

gardner48 Feb 7, 2026

Uh oh!

gardner48 Feb 7, 2026

Uh oh!

gardner48 Feb 7, 2026

Uh oh!

gardner48 Feb 7, 2026

Uh oh!

gardner48 Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	ark_mem->PostProcessStage = ProcessStage;
	ark_mem->PostProcessStage = ProcessStage;
	ark_mem->ps_data = ark_mem->user_data;

	ark_mem->PreProcessRHS = PreprocessRHS;
	ark_mem->PreProcessRHS = PreprocessRHS;
	ark_mem->ps_data = ark_mem->user_data;

	"status = failed preprocess stage, retval = %i", retval);
	"status = failed preprocess rhs, retval = %i", retval);

Conversation

drreynolds commented Jan 15, 2026

Step preprocessing vs postprocessing

Stage RHS preprocessing vs stage postprocessing

Uh oh!

drreynolds commented Jan 20, 2026

Uh oh!

drreynolds commented Jan 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants