zoomy_core.model.models.zeta_projection module

zoomy_core.model.models.zeta_projection module#

Three-Phase PDE Model Derivation: Phase 2 – Abstract zeta-space projection.

Takes PreProjectedEquations from Phase 1 and performs formal Galerkin projection in normalized zeta-space [0,1] WITHOUT choosing a basis or level.

The result contains abstract matrix symbols (M, A, D, B, Phi, phi_b) that are evaluated in Phase 3 with a specific basis.

Mathematical steps performed here:

  1. Coordinate transform z -> zeta = (z - b) / H, zeta in [0, 1]

  2. Ansatz substitution: u(t,x,zeta) = sum_k alpha_k(t,x) phi_k(zeta)

  3. Galerkin projection: multiply by phi_l(zeta), integrate int_0^1 … dzeta

  4. Integration by parts on d/dzeta terms

  5. Kinematic BCs at zeta=0 (bottom) and zeta=1 (surface)

  6. Stress BCs: free surface at top, Navier-slip at bottom

  7. Term tagging: temporal, flux, nonconservative, source

Usage:

from zoomy_core.model.models.model_derivation import derive_shallow_moments from zoomy_core.model.models.zeta_projection import project_to_zeta

state = StateSpace(dimension=2) pre = derive_shallow_moments(state) zeta = project_to_zeta(pre)

# Inspect abstract equations: print(zeta.summary()) print(zeta.latex_system())

# Phase 3: evaluate with a basis model = ProjectedModel(zeta, basis_type=Legendre_shifted, level=2)

class zoomy_core.model.models.zeta_projection.TermType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: str, Enum

Classification of projected term types for Phase 3 assembly.

MASS_TEMPORAL = 'mass_temporal'#
MASS_FLUX = 'mass_flux'#
MASS_FLUX_Y = 'mass_flux_y'#
INERTIA = 'inertia'#
ADVECTIVE_FLUX = 'advective_flux'#
PRESSURE_FLUX = 'pressure_flux'#
TOPOGRAPHY_NC = 'topography_nc'#
VERTICAL_ADVECTION_NC = 'vertical_advection_nc'#
MEAN_VELOCITY_NC = 'mean_velocity_nc'#
VISCOUS_SOURCE = 'viscous_source'#
SLIP_SOURCE = 'slip_source'#
ADVECTIVE_FLUX_CROSS = 'advective_flux_cross'#
class zoomy_core.model.models.zeta_projection.ZetaTerm(role, origin, term_type, matrix_deps, latex_str, component='x')#

Bases: object

A single term in the zeta-projected PDE system.

Carries physical classification, matrix dependencies, and LaTeX representation. Phase 3 dispatches on term_type to evaluate the term with concrete basis matrices.

Parameters:

  • role (Literal['temporal', 'flux', 'nonconservative', 'source']) –

  • origin (str) –

  • term_type (TermType) –

  • matrix_deps (tuple) –

  • latex_str (str) –

  • component (str) –

role: Literal['temporal', 'flux', 'nonconservative', 'source']#
origin: str#
term_type: TermType#
matrix_deps: tuple#
latex_str: str#
component: str = 'x'#
class zoomy_core.model.models.zeta_projection.ZetaProjectedEquations(state, continuity=<factory>, x_momentum=<factory>, y_momentum=<factory>, assumptions_applied=<factory>, dimension=2)#

Bases: object

Galerkin-projected shallow water equations in abstract zeta-space [0, 1].

Phase 2 output. Contains the formal Galerkin projection using abstract basis matrix symbols:

\[\begin{split}M_{lk} &= \int_0^1 \varphi_l\,\varphi_k\, d\zeta \\ A_{lij} &= \int_0^1 \varphi_l\,\varphi_i\,\varphi_j\, d\zeta \\ D_{lk} &= \int_0^1 \varphi'_l\,\varphi'_k\, d\zeta \\ B_{lij} &= \int_0^1 \varphi'_l\,\psi_j\,\varphi_i\, d\zeta \quad (\psi_j = \textstyle\int_0^\zeta \varphi_j\,d\zeta') \\ \Phi_l &= (M \cdot c)_l = \int_0^1 \varphi_l\, d\zeta \\ \varphi^b_l &= \varphi_l(0)\end{split}\]

These symbols are NOT evaluated – the actual numerical values depend on the choice of basis and level (Phase 3).

Parameters:

  • state (object) –

  • continuity (List[ZetaTerm]) –

  • x_momentum (List[ZetaTerm]) –

  • y_momentum (List[ZetaTerm]) –

  • assumptions_applied (List[str]) –

  • dimension (int) –

state: object#
continuity: List[ZetaTerm]#
x_momentum: List[ZetaTerm]#
y_momentum: List[ZetaTerm]#
assumptions_applied: List[str]#
dimension: int = 2#
property horizontal_dim#
all_equations()#
Return type:

Dict[str, List[ZetaTerm]]

summary()#
Return type:

str

latex_system()#

Return LaTeX string for the full projected PDE system.

Shows the raw (before M^{-1}) form of each equation with abstract matrix symbols. Summation convention on repeated indices.

Return type:

str

zoomy_core.model.models.zeta_projection.project_to_zeta(pre)#

Phase 2: Formal Galerkin projection into abstract zeta-space.

Takes the Phase 1 output (basis-independent shallow water equations) and writes down the Galerkin projection in terms of abstract basis matrix symbols.

No numerical integration is performed – the result is purely symbolic. A specific basis and level are chosen in Phase 3.

Returns:

Abstract projected equations ready for Phase 3 evaluation.

Return type:

ZetaProjectedEquations

Parameters:

pre (PreProjectedEquations) –