WIP: Initial IMEX tableau abstraction with generic perform_step! (ARS… by singhharsh1708 · Pull Request #3196 · SciML/OrdinaryDiffEq.jl

singhharsh1708 · 2026-03-19T08:01:30Z

Summary

This PR introduces a unified IMEX tableau-based framework and migrates the KenCarp and Kvaerno IMEX SDIRK families to use it.

The goal is to define IMEX methods entirely via tableau coefficients, removing the need for per-method perform_step! implementations and caches.

Included in this PR

IMEXTableau abstraction (explicit + implicit Butcher arrays)
Generic perform_step! implementation for IMEX methods
Migration of:
- KenCarp3, KenCarp4, KenCarp5, KenCarp47, KenCarp58
- Kvaerno3, Kvaerno4, Kvaerno5
Removal of all per-method caches and perform_step! implementations for these methods (~2000 LOC reduction)
ARS343 retained as a reference implementation

Verification

Convergence order verified for all migrated methods
Works for SplitODEProblem (both IIP and OOP)
Adaptive stepping verified
All existing SDIRK tests pass
No regressions observed in existing test suite

Notes

CFNLIRK3 is intentionally left unchanged as it does not fit the IMEX tableau structure (non-adaptive, different abstraction)
This completes the migration of IMEX SDIRK methods to a unified tableau-based implementation
Future work may extend this approach to additional IMEX families

Checklist

Appropriate tests were added
No public API breakage
Documentation updated where needed
Code follows SciML Style Guide and COLPRAC
All new documentation uses public API

singhharsh1708 · 2026-03-20T16:47:19Z

@ChrisRackauckas This PR introduces a prototype IMEX tableau abstraction and generic perform_step! dispatch.

Fixed LTS precompilation issues (removed new algorithms from umbrella exports)
Verified SDIRK test suite passes locally
Float32 support confirmed
Remaining CI failures are expected as this is a WIP prototype focused on architecture and design.

singhharsh1708 · 2026-03-22T04:37:02Z

@ChrisRackauckas what about this is this working fine and has correct structure?

ChrisRackauckas · 2026-03-23T11:47:32Z

It looks like a good start but it needs all of the details of the other SDIRK methods

singhharsh1708 · 2026-03-23T18:46:24Z

@ChrisRackauckas Migrated the full KenCarp/Kvaerno family to IMEXTableau and removed the per-method implementations. All tests are passing.

ChrisRackauckas · 2026-03-24T10:08:52Z

lib/OrdinaryDiffEqSDIRK/src/algorithms.jl

    )
 end

+abstract type OrdinaryDiffEqNewtonAdaptiveIMEXAlgorithm{CS, AD, FDT, ST, CJ} <:


top level should be in core.

ChrisRackauckas · 2026-03-24T10:09:36Z

lib/OrdinaryDiffEqSDIRK/src/generic_imex_perform_step.jl

+end
+
+function alg_cache(
+        alg::OrdinaryDiffEqNewtonAdaptiveIMEXAlgorithm, u, rate_prototype, ::Type{uEltypeNoUnits},


this doesn't cover all imex

ChrisRackauckas · 2026-03-24T10:10:49Z

lib/OrdinaryDiffEqSDIRK/src/generic_imex_perform_step.jl

+    if integrator.f isa SplitFunction && !repeat_step && !integrator.last_stepfail
+        f_impl(zs[1], integrator.uprev, p, integrator.t)
+        zs[1] .*= dt


Only ESDIRK?

ChrisRackauckas · 2026-03-24T10:11:30Z

lib/OrdinaryDiffEqSDIRK/src/imex_tableaus.jl

@@ -0,0 +1,1504 @@
+struct IMEXTableau{T, T2}


ESDIRKIMEX?

ChrisRackauckas · 2026-03-24T10:12:12Z

lib/OrdinaryDiffEqSDIRK/src/kencarp_kvaerno_perform_step.jl

    nlsolver.z = z₂

-    @.. broadcast = false tmp = uprev + γ * z₁
+    @.. broadcast = false tmp = uprev


also while updating these, please replace all uses of @.. broadcast=false with @.. (brodcast=false is the default)

ChrisRackauckas · 2026-03-24T10:12:53Z

lib/OrdinaryDiffEqSDIRK/src/OrdinaryDiffEqSDIRK.jl

    SFSDIRK4, SFSDIRK5, CFNLIRK3, SFSDIRK6,
-    SFSDIRK7, SFSDIRK8, ESDIRK436L2SA2, ESDIRK437L2SA, ESDIRK547L2SA2, ESDIRK659L2SA
+    SFSDIRK7, SFSDIRK8, ESDIRK436L2SA2, ESDIRK437L2SA, ESDIRK547L2SA2, ESDIRK659L2SA,
+    OrdinaryDiffEqNewtonAdaptiveIMEXAlgorithm, ARS343


abstract types shouldn't export here.

ChrisRackauckas · 2026-03-24T10:13:00Z

Project.toml

 CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
+DiffEqDevTools = "f3b72e0c-5b89-59e1-b016-84e28bfd966d"


ChrisRackauckas · 2026-03-24T10:13:10Z

Project.toml

 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 MuladdMacro = "46d2c3a1-f734-5fdb-9937-b9b9aeba4221"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+ODEProblemLibrary = "fdc4e326-1af4-4b90-96e7-779fcce2daa5"


ChrisRackauckas · 2026-03-24T10:16:21Z

Looks generally good. Needs a lot more to get the rest of the IMEX methods, but it's probably good to merge a version with just these ESDIRKs supported. Left a bunch of comments.

singhharsh1708 · 2026-03-24T11:55:24Z

@ChrisRackauckas Addressed all review comments:

Scoped IMEX implementation to ESDIRK methods (renamed types accordingly)
Cleaned up abstract type usage and exports
Fixed perform_step artifacts
Removed unnecessary dependencies
Removed all remaining @.. broadcast=false usages in the ESDIRK IMEX code paths.
All tests passing and formatting clean. Let me know if anything else should be adjusted.
Removed all remaining @.. broadcast=false usages in the ESDIRK IMEX code paths.

singhharsh1708 · 2026-03-25T08:26:09Z

@ChrisRackauckas
Final check: all changes have been tested and are working as expected.

Migrated KenCarp and Kvaerno methods to the generic ESDIRK IMEX tableau
Verified OOP, IIP, and SplitODE behavior
All migrated methods pass tests with expected accuracy
No regressions observed in non-migrated methods
Runic formatting clean
Additionally, corrected the ARS343 embedded error estimator to satisfy order conditions, improving adaptive stepping behavior.
Please let me know if anything else should be addressed.

ChrisRackauckas · 2026-03-25T09:09:47Z

Additionally, corrected the ARS343 embedded error estimator to satisfy order conditions, improving adaptive stepping behavior.

Can you explain that a bit more?

singhharsh1708 · 2026-03-25T09:12:12Z

earlier ARS343 was using a placeholder embedded method for error estimation:
b̃ = b - e₄ (i.e., using only the last stage)
While this keeps Σ b̃ = 0, it does not satisfy the second order condition
Σ b̃ᵢ cᵢ = 0, so it does not form a valid lower-order embedded pair.
As a result, the error estimate was not consistent, and adaptive stepping
could behave poorly at tighter tolerances.
I replaced it with coefficients that satisfy both order conditions:
Σ b̃ᵢ = 0
Σ b̃ᵢ cᵢ = 0
which correspond to a proper order-(p−1) embedded method for this
3rd-order scheme. With this change, the error estimate behaves correctly
and the solver shows expected convergence under tighter tolerances.
The underlying ARS343 method itself is unchanged — only the embedded
error estimator used for adaptivity.

ChrisRackauckas · 2026-03-25T09:13:58Z

The paper does not have an error estimator, so just don't make it adaptive.

singhharsh1708 · 2026-03-25T09:55:04Z

@ChrisRackauckas got it that makes sense,
I’ve reverted the embedded error estimator change and made ARS343 non-adaptive.

ChrisRackauckas · 2026-03-25T09:56:17Z

It doesn't look like it's not adaptive. It should set the trait based on whether btilde = nothing.

singhharsh1708 · 2026-03-25T10:08:05Z

@ChrisRackauckas updated ARS343 to set btilde = nothing so adaptivity is disabled via the tableau trait, and guarded the adaptive path accordingly.

…343 prototype)

…-method implementations

…review feedback

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ptive stepping)

…lementation and remove per-method caches/perform_step

singhharsh1708 · 2026-03-27T16:34:00Z

@ChrisRackauckas migrated the remaining ESDIRK methods (ESDIRK54I8L2SA, ESDIRK436L2SA2, ESDIRK437L2SA, ESDIRK547L2SA2, ESDIRK659L2SA) to the tableau-based implementation.

singhharsh1708 · 2026-03-27T16:36:22Z

one follow up question :Methods such as ImplicitEuler, Trapezoid, TRBDF2, SDIRK2, SDIRK22, Cash4, Hairer4, and Hairer42 have different structural properties (non-IMEX formulations and different stage structures), and may not directly fit into the current ESDIRK IMEX abstraction. Would it make sense to:
introduce a separate tableau abstraction for pure SDIRK methods, or
generalize the current framework to support both IMEX and non-IMEX SDIRK methods?

oscardssmith · 2026-03-27T17:20:51Z

IMO either is fine (but we probably want to do either as a separate PR.

singhharsh1708 force-pushed the imex-tableau-prototype branch from ee82a23 to 86409c9 Compare March 20, 2026 19:40

ChrisRackauckas reviewed Mar 24, 2026

View reviewed changes

lib/OrdinaryDiffEqSDIRK/src/imex_tableaus.jl Outdated

@@ -0,0 +1,1504 @@

struct IMEXTableau{T, T2}

Copy link
Copy Markdown

Member

ChrisRackauckas Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ESDIRKIMEX?

ChrisRackauckas reviewed Mar 24, 2026

View reviewed changes

singhharsh1708 force-pushed the imex-tableau-prototype branch 2 times, most recently from 7e4ce55 to 333d24b Compare March 25, 2026 07:20

Harsh Singh added 6 commits March 27, 2026 19:13

WIP: Initial IMEX tableau abstraction with generic perform_step! (ARS…

d1278a5

…343 prototype)

WIP: IMEX tableau prototype - fix perform_step and formatting

bdc14dc

Fix IMEX prototype: remove ARS343 re-export (LTS safe)

cb2dbd3

Fix initialize! return values for IMEX caches (ensure return nothing)

58c9be4

refactor(IMEX): migrate KenCarp/Kvaerno to IMEXTableau and remove per…

1c2d108

…-method implementations

Refactor: restrict IMEX implementation to ESDIRK methods and address …

8ee2b9f

…review feedback

Harsh Singh and others added 6 commits March 27, 2026 19:13

Cleanup: remove redundant @.. broadcast=false usage

8e3a179

Reset Project.toml to upstream master

d9c6e02

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix ARS343 embedded error estimator (satisfy order conditions for ada…

d2430c5

…ptive stepping)

Revert ARS343 embedded estimator change

07123d2

Make ARS343 non-adaptive via btilde = nothing and guard adaptive path

2f49b48

refactor(IMEX): migrate remaining ESDIRK methods to tableau-based imp…

b8bdd3f

…lementation and remove per-method caches/perform_step

singhharsh1708 force-pushed the imex-tableau-prototype branch from 8cc211a to b8bdd3f Compare March 27, 2026 16:27

Uh oh!

Conversation

singhharsh1708 commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Included in this PR

Verification

Notes

Checklist

Uh oh!

singhharsh1708 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

singhharsh1708 commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChrisRackauckas commented Mar 23, 2026

Uh oh!

singhharsh1708 commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

ChrisRackauckas commented Mar 24, 2026

Uh oh!

singhharsh1708 commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

singhharsh1708 commented Mar 25, 2026

Uh oh!

ChrisRackauckas commented Mar 25, 2026

Uh oh!

singhharsh1708 commented Mar 25, 2026

Uh oh!

ChrisRackauckas commented Mar 25, 2026

Uh oh!

singhharsh1708 commented Mar 25, 2026

Uh oh!

ChrisRackauckas commented Mar 25, 2026

Uh oh!

singhharsh1708 commented Mar 25, 2026

Uh oh!

singhharsh1708 commented Mar 27, 2026

Uh oh!

singhharsh1708 commented Mar 27, 2026

Uh oh!

oscardssmith commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

singhharsh1708 commented Mar 19, 2026 •

edited

Loading

singhharsh1708 commented Mar 20, 2026 •

edited

Loading

singhharsh1708 commented Mar 22, 2026 •

edited

Loading

singhharsh1708 commented Mar 23, 2026 •

edited

Loading

singhharsh1708 commented Mar 24, 2026 •

edited

Loading