zoomy_core.analysis.pencil module

zoomy_core.analysis.pencil module#

Generalised-eigenvalue (pencil) form for analysis.

A linearised PDE system can be written in the form

M_t · ∂_t δq + M_xa · ∂_xa δq + M_0 · δq = 0 (sum over axis a)

where M_t, M_xa, M_0 are constant matrices (coefficients evaluated at the base state). Plane-wave ansatz δq = q̂ e^(i(k·x − ωt)) reduces this to

[-iω M_t + i k · (Σ_a n_a M_xa) + M_0] q̂ = 0

where n is the normal direction (Σ n_a² = 1). Dividing by ik and writing λ = ω/k gives the generalised eigenvalue problem

[Σ_a n_a M_xa + (1 / (ik)) M_0] q̂ = λ M_t q̂.

For the principal symbol (high-k limit, or systems with M_0 = 0):

A_n q̂ = λ M_t q̂ A_n := Σ_a n_a M_xa.

This module extracts (M_t, [M_xa], M_0) mechanically from a linearised SystemModel and computes the generalised eigenvalues either symbolically (sp.solve(charpoly)) or numerically (scipy.linalg.eig).

zoomy_core.analysis.pencil.extract_quasilinear_pencil(linear_sm)#

Extract (M_t, [M_xa], M_0) from a linearised SystemModel.

Each entry of the linearised SystemModel’s operator slots is expected to be linear in the perturbation state.

Returns:

  • M_t ((n_eq × n_state) sp.Matrix — coefficient of ∂_t δq_j.)

  • M_xa (list of (n_eq × n_state) sp.Matrix — one per spatial axis.)

  • M_0 ((n_eq × n_state) sp.Matrix — coefficient of δq_j (no derivative).)

Return type:

Tuple[MutableDenseMatrix, List[MutableDenseMatrix], MutableDenseMatrix]

zoomy_core.analysis.pencil.generalised_eigenvalues(M_x, M_t, *, lam=None, simplify=True)#

Symbolic generalised eigenvalues of the pencil (M_x, M_t).

Solves det(M_x − λ M_t) = 0 for λ. Returns a list of solutions.

Caveat — symbolic charpoly degree blows up fast. For larger systems use sample_generalised_eigenvalues (numerical).

Parameters:

  • M_x (MutableDenseMatrix) –

  • M_t (MutableDenseMatrix) –

  • lam (Optional[Symbol]) –

  • simplify (bool) –

Return type:

List[Expr]

zoomy_core.analysis.pencil.symbolic_eigenvalues_at(sm, base_state, *, axis=0, simplify=True)#

One-shot helper: linearise sm (a SystemModel) at base_state, extract the principal-symbol pencil (M_x_axis, M_t), and return the symbolic generalised eigenvalues.

Parameters:

  • sm – a SystemModel.

  • base_state (Dict) – dict {state_sym: value} for every state entry.

  • axis (int) – which spatial direction’s pencil to use (default 0).

  • simplify (bool) – apply sp.expand to the characteristic poly.

Returns:

list of symbolic eigenvalues.

Return type:

List[Expr]

zoomy_core.analysis.pencil.sample_generalised_eigenvalues(M_x, M_t, parameter_samples, *, dtype=<class 'complex'>, drop_infinite=False)#

For each sample (a dict of symbolic-value → numeric-value), return the numerical generalised eigenvalues of (M_x, M_t) at that sample.

Uses scipy.linalg.eig(A, B) which solves A v = λ B v even when B is singular (in which case some λ are returned as inf). drop_infinite=True filters those out.

Parameters:

  • M_x (MutableDenseMatrix) –

  • M_t (MutableDenseMatrix) –

  • parameter_samples (List[Dict]) –

  • drop_infinite (bool) –

Return type:

List[ndarray]