zoomy_core.fvm.imex_ark module

zoomy_core.fvm.imex_ark module#

IMEX additive-Runge-Kutta integrator for index-1 DAEs.

Implements Ascher-Ruuth-Spiteri (1997, DOI 10.1016/S0168-9274(97)00056-1) ARS232 and ARS343 schemes for systems of the form

M_t · y’ = f_E(t, y) + f_I(t, y), M_t = diag(dyn_mask),

where dyn_mask[i] = True for evolution rows and False for algebraic constraint rows. For algebraic rows the implicit residual is the constraint f_I(t, y)[i] = 0 itself; the per-stage Newton iteration enforces it exactly.

Verified at order 2 (ARS232) and order 3 (ARS343) on linear and nonlinear index-1 toy DAEs in tests/unit/zoomy_core/test_imex_ark.py. Constraint residual stays at floating-point precision.

class zoomy_core.fvm.imex_ark.IMEXTableau(name: 'str', order: 'int', A_E: 'np.ndarray', b_E: 'np.ndarray', c_E: 'np.ndarray', A_I: 'np.ndarray', b_I: 'np.ndarray', c_I: 'np.ndarray', s: 'int')#

Bases: object

Parameters:

  • name (str) –

  • order (int) –

  • A_E (ndarray) –

  • b_E (ndarray) –

  • c_E (ndarray) –

  • A_I (ndarray) –

  • b_I (ndarray) –

  • c_I (ndarray) –

  • s (int) –

name: str#
order: int#
A_E: ndarray#
b_E: ndarray#
c_E: ndarray#
A_I: ndarray#
b_I: ndarray#
c_I: ndarray#
s: int#
class zoomy_core.fvm.imex_ark.ExplicitButcherTableau(name, order, A, b, c, s)#

Bases: object

Butcher tableau for an explicit Runge-Kutta scheme.

Used by explicit_rk_step() for predictor / explicit-only substeps (e.g. the Chorin split’s hyperbolic predictor). Lives alongside IMEXTableau so the time-stepping zoo is one module — same construction style, just no implicit half.

Parameters:

  • name (str) –

  • order (int) –

  • A (ndarray) –

  • b (ndarray) –

  • c (ndarray) –

  • s (int) –

name: str#
order: int#
A: ndarray#
b: ndarray#
c: ndarray#
s: int#
zoomy_core.fvm.imex_ark.euler()#

Forward Euler (RK1). Single stage, used at reconstruction order 1.

Return type:

ExplicitButcherTableau

zoomy_core.fvm.imex_ark.ssprk2()#

Heun’s method / SSP-RK2. Two stages, order 2.

Standard for explicit hyperbolic transport at order 2 — preserves monotonicity under CFL when paired with a TVD spatial limiter.

Return type:

ExplicitButcherTableau

zoomy_core.fvm.imex_ark.ssprk3()#

Shu-Osher SSP-RK3. Three stages, order 3.

Strong-stability-preserving — same TVD property as SSP-RK2 but one order higher. Slightly more expensive (3 RHS evaluations).

Return type:

ExplicitButcherTableau

zoomy_core.fvm.imex_ark.explicit_rk_step(t, y, dt, table, f)#

Advance y one explicit RK step under any Butcher tableau.

Shape-agnostic: y and f(t, y) can be any array shape (1-D, 2-D state-on-mesh, etc.) so long as they match. For partial updates (e.g. a Chorin predictor that only touches certain state rows) the caller returns zeros for the untouched slots in f.

No allocation per stage beyond the stage-state arrays themselves; safe to call inside a time loop.

Parameters:

  • t (float) –

  • y (ndarray) –

  • dt (float) –

  • table (ExplicitButcherTableau) –

  • f (Callable[[float, ndarray], ndarray]) –

Return type:

ndarray

zoomy_core.fvm.imex_ark.ars232()#

ARS(2,3,2) — 2nd-order, stiffly accurate.

Reference: Ascher-Ruuth-Spiteri 1997 Sec. 2.6, Table 1.

Return type:

IMEXTableau

zoomy_core.fvm.imex_ark.ars343()#

ARS(3,4,3) — 3rd-order, stiffly accurate.

Reference: Ascher-Ruuth-Spiteri 1997 Sec. 2.7, Table 2.

Return type:

IMEXTableau

zoomy_core.fvm.imex_ark.imex_ark_step(t, y, dt, tab, f_E, f_I, J_I, dyn_mask, *, newton_tol=1e-10, newton_maxit=40)#

One IMEX-ARK step of M_t y' = f_E + f_I with M_t = diag(dyn_mask).

Stage residual:

R[dyn] = (Y - rhs_explicit)[dyn] - dt·γ_ii·f_I(Y)[dyn] R[alg] = f_I(Y)[alg]

Parameters:

  • t (float) –

  • y (ndarray) –

  • dt (float) –

  • tab (IMEXTableau) –

  • f_E (Callable[[float, ndarray], ndarray]) –

  • f_I (Callable[[float, ndarray], ndarray]) –

  • J_I (Callable[[float, ndarray], ndarray]) –

  • dyn_mask (ndarray) –

  • newton_tol (float) –

  • newton_maxit (int) –

Return type:

ndarray

zoomy_core.fvm.imex_ark.integrate(y0, t0, t_end, dt, tab, f_E, f_I, J_I, dyn_mask, *, newton_tol=1e-10, newton_maxit=40)#

Fixed-step IMEX-ARK integration from t0 to t_end.

Returns a list of (t, y) snapshots including the initial state.

Parameters:

  • y0 (ndarray) –

  • t0 (float) –

  • t_end (float) –

  • dt (float) –

  • tab (IMEXTableau) –

  • f_E (Callable[[float, ndarray], ndarray]) –

  • f_I (Callable[[float, ndarray], ndarray]) –

  • J_I (Callable[[float, ndarray], ndarray]) –

  • dyn_mask (ndarray) –

  • newton_tol (float) –

  • newton_maxit (int) –

Return type:

List[Tuple[float, ndarray]]