zoomy_core.analysis.system_model_analysis module

zoomy_core.analysis.system_model_analysis module#

SystemModel-based analysis: linearise + dispersion + eigenvalues.

Operates directly on zoomy_core.model.models.system_model.SystemModel — no PDESystem wrapper, no linearise-on-equation-tree machinery. The model’s stored sympy matrices already encode the operator surface; analysis is straightforward symbolic substitution + eigenvalue solve.

Three entry points:

  • linearise_system_model() — substitute a base state into the flux / NCP / source / hydrostatic-pressure / mass matrices and return a new SystemModel whose matrices are constant in the state Symbols (only depend on coordinates and parameters).

  • plane_wave_dispersion() — given a constant-coefficient linearised SystemModel, build the principal-symbol pencil (M_t, M_x[axis], M_0) and return the symbolic eigenvalues ω(k) (or equivalently λ = ω/k solving det(M_x − λ M_t) = 0).

  • hyperbolic_eigenvalues() — same pencil but returning the generalized eigenvalues of (M_x[axis], M_t) directly via zoomy_core.analysis.pencil.generalised_eigenvalues().

For shapes where the analyst wants Sum/Indexed form (linear stability with symbolic k, parameter-sweep hyperbolicity, etc.) the substitution dict accepts any sympy values — base_state[h] = h0 keeps h0 symbolic.

zoomy_core.analysis.system_model_analysis.linearise_system_model(sm, base_state, *, parameters=None)#

Substitute base_state into every operator matrix; return a new SystemModel whose matrices are constant in the state.

Parameters:

  • sm (SystemModel) – The source operator-form system.

  • base_state (dict) – Map of state Symbol → base value. Missing entries are left symbolic. Aux-state Symbols may also be substituted.

  • parameters (dict, optional) – Additional parameter substitutions (e.g. {ez: 1, g: 9.81}). Combined with base_state for the substitution.

Return type:

SystemModel

zoomy_core.analysis.system_model_analysis.plane_wave_dispersion(sm, base_state, *, axis=0, parameters=None, return_omega_k=True)#

Compute the dispersion of sm linearised at base_state.

Two output modes are supported (controlled by return_omega_k):

  • return_omega_k=True (default, fixes G7 from the plan): assemble the full plane-wave matrix M(ω, k) from the linearised system and solve det M(ω, k) = 0 for the true ω(k) curves — symbolic functions of k rather than just eigenvalues at a fixed base state.

  • return_omega_k=False (legacy): return only generalised eigenvalues of (M_x, M_t) — phase velocities at the base state, no k-dependence.

Returns a dict with:

  • M_t — mass matrix at base state.

  • M_x — quasilinear matrix at base state in direction axis.

  • M_0 — -∂S/∂Q at base state.

  • eigenvalues — generalised eigenvalues (legacy, always present).

  • omega_solutions (only when return_omega_k=True) — list of symbolic ω(k) solutions of det M(ω, k) = 0.

  • phase_velocity_solutions (only when return_omega_k=True) — [ω/k for ω in omega_solutions].

  • k (only when return_omega_k=True) — the wavenumber symbol.

  • omega (only when return_omega_k=True) — the angular‑frequency symbol.

Parameters:

  • sm (SystemModel) –

  • base_state (Dict[Any, Any]) –

  • axis (int) –

  • parameters (Optional[Dict[Any, Any]]) –

  • return_omega_k (bool) –

Return type:

Dict[str, Any]

zoomy_core.analysis.system_model_analysis.hyperbolic_eigenvalues(sm, base_state, *, axis=0, parameters=None)#

Convenience: return only the eigenvalues from plane_wave_dispersion().

Useful for hyperbolicity sampling: real eigenvalues = hyperbolic; complex conjugate pairs = elliptic mode = ill-posed initial-value problem.

Parameters:

  • sm (SystemModel) –

  • base_state (Dict[Any, Any]) –

  • axis (int) –

  • parameters (Optional[Dict[Any, Any]]) –

Return type:

List[Expr]