zoomy_core.model.splitter module

zoomy_core.model.splitter module#

Predictor / pressure / corrector splitter for chain-DAE SystemModels.

Mechanises the substitution rule from tutorials/vam/escalante2024_poisson_generic.py (the verified hand-coded reference).

The splitter consumes a SystemModel whose equation_names follow the chain-DAE convention:

  • mass — mass evolution row

  • xmom_j0, xmom_j1, … — x-momentum projections

  • zmom_j0, zmom_j1, … — z-momentum projections

  • cont_j1, cont_j2, … — pressure-projection

    (algebraic) constraint rows

The splitter exposes two entry points:

  • build_pressure_elliptic_block() — the irreducible algebraic core (extracts T_u[k], T_w[k], builds the elliptic rows).

  • split_for_pressure() — wraps the core into three rectangular sub-SystemModels (predictor / pressure / corrector) sharing the same state vector.

zoomy_core.model.splitter.build_pressure_elliptic_block(sm, pressure_vars, dt, *, bottom=None)#

Build the pressure-stage elliptic block for SM_press.

Parameters:

  • sm (SystemModel) – Chain-DAE SystemModel (e.g. SystemModel.from_model( VAMModelGalerkin(level=1))). Must carry equation_names with the canonical mass / xmom_j / zmom_j / cont_j layout.

  • pressure_vars (Sequence) – Pressure mode state Symbols (e.g. [P_0, P_1] for VAM(1,2,2)). Internally converted to Function form to match the residual representation produced by SystemModel.reconstruct_residuals().

  • dt (sp.Symbol) – Symbolic time-step.

  • bottom (optional) – Bottom-topography Function b(x). If None, located by scanning equation residuals for a Function named b.

Returns:

  • dict with keys rows, U_tilde, W_tilde, T_u, T_w,

  • U_corr, W_corr, pressure_vars, h, bottom, t,

  • x. All entries are in Function form (coordinate-dependent).

zoomy_core.model.splitter.verify_p_linearity(rows, pressure_vars, x)#

Verify each row is linear in (P_l, ∂_x P_l, ∂_xx P_l).

zoomy_core.model.splitter.split_for_pressure(sm, pressure_vars, dt, *, bottom=None)#

Split a chain-DAE SystemModel into three SystemModel sub-systems (SM_pred, SM_press, SM_corr) sharing the same state vector Q.

zoomy_core.model.splitter.split_simple(sm, pressure_vars, dt, *, bottom=None)#

Minimal manual splitter — copies the SystemModel, then deletes rows and terms.

Algorithm:

  1. Copy the parent SystemModel three times → (SM_pred, SM_press, SM_corr).

  2. SM_pred: keep only the rows whose equation_name does NOT start with cont_j (evolution rows including any trivial ones like b_eq for bathymetry-as-state). Then ZERO out every pressure-state-dependent term: F.xreplace({P_k: 0}), same for P, B, S. The predictor thus advances with kinetic + gravity + NCP and ANY non-pressure source — exactly like the OLD PredictorCorrectorSolver did with its flux-only step.

  3. SM_press: keep only the cont_j* rows, with the dt-baked U_corr substitution applied (reuses build_pressure_elliptic_block() for the substitution machinery). This is the elliptic block in (P_0, P_1) that the implicit Newton-Krylov solver targets.

  4. SM_corr: the closed-form state_update formula Q[k] ← Q[k] − (dt/h)·T_u_k(P) (also from build_pressure_elliptic_block()). This is the projection-corrector that applies the freshly-solved pressure to the momentum modes.

Parameters:

  • sm (SystemModel) – Parent system. Must carry equation_names whose values flag algebraic rows by the cont_j prefix.

  • pressure_vars (Sequence[sp.Symbol]) – Pressure state symbols (e.g. [P_0, P_1]).

  • dt (sp.Symbol) – Symbolic time-step (gets baked into SM_press / SM_corr operators).

  • bottom (optional) – Forwarded to build_pressure_elliptic_block().

Return type:

SplitForPressureResult

class zoomy_core.model.splitter.SplitForPressureResult(SM_pred, SM_press, SM_corr)#

Bases: object

Three sub-SystemModels produced by split_for_pressure().

For VAM(1, 2, 2) on Q = [h, U_0, U_1, W_0, W_1, P_0, P_1]:

  • SM_pred — predictor: 5 evolution rows (mass + 2 xmom + 2 zmom) updating Q[0..4] = h, U_k, W_k with P_k frozen at P_k^n.

  • SM_press — pressure stage: 2 algebraic rows (the elliptic block in (P_0, P_1)) updating Q[5..6]. Mass matrix all-zero.

  • SM_corr — corrector: 4 algebraic update rows.

Parameters:

  • SM_pred (object) –

  • SM_press (object) –

  • SM_corr (object) –

SM_pred: object#
SM_press: object#
SM_corr: object#