perturbation.EigenmodeResult
perturbation.EigenmodeResult(
omega,
modes,
residuals,
L,
est,
n_solve,
n_edges,
contour=None,
node_names=(),
expected=None,
terminals=None,
geometry=None,
storage=None,
)Validated free-oscillation eigenmodes of the perturbation network.
Frequencies are reported in Hz (Re(omega)/(2*pi)) and growth rates in 1/s (-Im(omega)); a mode is unstable iff its growth rate is positive (equivalently Im(omega) < 0). Mode shapes are stored as the full nodal eigenvector and projected to characteristic amplitudes (f, g, h) on demand.
Attributes
| Name | Type | Description |
|---|---|---|
| omega | ndarray | Complex modal angular frequencies (rad/s), shape (n_modes,). |
| modes | ndarray | Unit-norm nodal eigenvectors (mode shapes in solution variables), shape (n_modes, n_col). |
| residuals | ndarray | Per-mode residual \|\|A_s(omega) v_s\|\| / max\|A_s(omega)\| on the equilibrated operator A_s = D_r A D_c (see :class:_ResidualScale); dimensionless, and far below residual_tol for a converged mode. |
| L | list of ndarray | Per-edge dx_to_char (3x3) maps at the frozen mean state. |
| est | ndarray | Frozen mean edge-state table (with caloric columns filled). |
| n_solve | int | Solve-variable stride per edge in the nodal vector. |
| n_edges | int | Number of edges. |
| contour | Contour | The search contour the modes were found in. |
| node_names | tuple | Per-node element labels (for plot annotation). |
| expected | int or None | Eigenvalue count the region must contain by the argument principle (completeness certificate); None if certification was disabled or unavailable. Compare against :attr:n_modes via :attr:certified. |
Methods
| Name | Description |
|---|---|
| animate_mode | Animate one or more modes’ spatial shapes over one phase cycle (slider + play). |
| boundary_power | Acoustic-power budget across the boundaries for mode i. |
| energy_balance | Acoustic-energy budget and energy-derived growth rate of mode i. |
| field_along_network | Reconstruct mode i’s spatial field along every root->leaf path. |
| intensity_along_network | Acoustic intensity (or energy density) along the developed length, for mode i. |
| mode_shape | Mode i projected onto every edge, shape (n_edges, n_char). |
| mode_waves | Characteristic amplitudes (f, g, h) of mode i at edge. |
| plot_boundary_power | Bar chart of each boundary’s signed acoustic-power share for mode i. |
| plot_mode | Plot the shape of mode i (wave magnitude and phase along the edges). |
| plot_spectrum | Plot the spectrum: growth rate vs modal frequency, with the stability boundary. |
| summary | List of per-mode dicts: frequency (Hz), growth rate (1/s), damping ratio, residual. |
animate_mode
perturbation.EigenmodeResult.animate_mode(
i,
*,
variable='p',
basis=None,
root=None,
n_x=160,
n_frames=60,
normalize=True,
envelope=True,
**layout,
)Animate one or more modes’ spatial shapes over one phase cycle (slider + play).
Draws the instantaneous physical perturbation Re{psi(x) e^{i theta}} along the developed length, sweeping the phase theta with a play button, framed by the static +/- |psi(x)| envelope. A serial network is one trace; a branched one shows one trace per root->leaf path, with compact elements marked where the field jumps.
Several quantities can share the figure. Pass a list of variable names, or a basis flavor (which expands to its three components), to overlay variables; pass a list for i to overlay modes. Overlaid modes generally have different frequencies, so they animate on a common real-time axis: the first listed mode is the reference and completes exactly one cycle per loop, while the others advance at f_k / f_ref and beat against it (their relative phase drifts – this is physical, not an artefact).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int or sequence of int | Mode index, or several to overlay. | required |
| variable | str or sequence of str | Plotted quantity, or several to overlay (see :meth:field_along_network); default "p". Ignored when basis is given. |
'p' |
| basis | str | A flavor from :data:nefes.perturbation.operator.characteristics.BASIS_LABELS ("char", "primitive", "network", "riemann", "pu_entropy", "pu_rho"); overlays its three components and overrides variable. |
None |
| root | int | Developed-length origin element (default: a mean-flow inlet). | None |
| n_x | int | Interior samples per duct (default 160). | 160 |
| n_frames | int | Phase frames over one cycle of the reference mode (default 60). | 60 |
| normalize | bool | Scale each overlaid quantity’s peak magnitude to 1 (default True; eigenvectors are arbitrary scale). | True |
| envelope | bool | Shade the +/- \|psi(x)\| span behind each animated line (default True); set False to drop the background shading. |
True |
| **layout | Forwarded to Figure.update_layout. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
boundary_power
perturbation.EigenmodeResult.boundary_power(i=0)Acoustic-power budget across the boundaries for mode i.
Attributes a mode’s growth to the boundaries that feed or drain its acoustic energy (Myers flux through each terminal face).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index (default 0). | 0 |
Returns
| Name | Type | Description |
|---|---|---|
| nefes.perturbation.fields.power.BoundaryPower | Per-terminal signed power shares; .net is the energy growth dE/dt and .sign_consistent cross-checks it against the growth rate. |
See also
nefes.perturbation.fields.power : the Myers energy-flux convention these shares use. energy_balance : the interior + boundary ledger and the growth rate it implies.
energy_balance
perturbation.EigenmodeResult.energy_balance(i=0)Acoustic-energy budget and energy-derived growth rate of mode i.
Forms the node-wise ledger (interior generation, boundary flux, stored duct energy) and returns the growth rate it implies, (generation + boundary_flux) / (2 E), beside this result’s contour eigenvalue – a cross-check on the eigensolver.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index (default 0). | 0 |
Returns
| Name | Type | Description |
|---|---|---|
| nefes.perturbation.fields.power.ModalEnergyBalance |
See also
boundary_power : the per-terminal breakdown of the boundary-flux term in this ledger. nefes.perturbation.fields.power : the Myers energy-density/flux convention it integrates.
field_along_network
perturbation.EigenmodeResult.field_along_network(
i,
*,
variable='p',
spec=None,
root=None,
n_x=160,
)Reconstruct mode i’s spatial field along every root->leaf path.
The continuous perturbation field inside every duct, recovered analytically from the mode’s face wave-amplitudes; see :func:nefes.perturbation.fields.modeshape.reconstruct_field.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index. | required |
| variable | str | Plotted quantity ("p", "u", "rho", "mdot", "f", "g", "h"); default "p". Ignored when spec is given. |
'p' |
| spec | tuple | A (basis_flavor, component) pair (e.g. from :func:nefes.perturbation.fields.modeshape.resolve_specs) selecting any basis component directly; overrides variable. |
None |
| root | int | Developed-length origin element (default: a mean-flow inlet). | None |
| n_x | int | Interior samples per duct (default 160). | 160 |
Returns
| Name | Type | Description |
|---|---|---|
| list of nefes.perturbation.fields.modeshape.PathField |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If the result carries no geometry (constructed without a problem). |
intensity_along_network
perturbation.EigenmodeResult.intensity_along_network(
i,
*,
energy_density=False,
root=None,
n_x=160,
)Acoustic intensity (or energy density) along the developed length, for mode i.
The spatial companion of :meth:field_along_network: reconstructs the Myers acoustic intensity I(x) [W/m^2] (downstream positive) – or the energy density e(x) [J/m^3] when energy_density=True – along every root->leaf path of mode i. A real diagnostic in arbitrary (mode-scale) units.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index. | required |
| energy_density | bool | Return the energy density instead of the intensity (default False). |
False |
| root | int | Developed-length origin element (default: a mean-flow inlet). | None |
| n_x | int | Interior samples per duct (default 160). | 160 |
Returns
| Name | Type | Description |
|---|---|---|
| list of nefes.perturbation.fields.modeshape.PathField |
mode_shape
perturbation.EigenmodeResult.mode_shape(i, basis='char')Mode i projected onto every edge, shape (n_edges, n_char).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index. | required |
| basis | str | Variable flavor (characteristics.BASIS_LABELS; e.g. "char" for (f, g, h), "primitive" for (rho', u', p')). Default "char". |
'char' |
Returns
| Name | Type | Description |
|---|---|---|
| ndarray | Complex shape (n_edges, n_char). |
mode_waves
perturbation.EigenmodeResult.mode_waves(i, edge)Characteristic amplitudes (f, g, h) of mode i at edge.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index. | required |
| edge | int | Edge id. | required |
Returns
| Name | Type | Description |
|---|---|---|
| ndarray | Complex shape (n_char,) – the wave amplitudes of the mode shape. |
plot_boundary_power
perturbation.EigenmodeResult.plot_boundary_power(i=0, **kwargs)Bar chart of each boundary’s signed acoustic-power share for mode i.
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
plot_mode
perturbation.EigenmodeResult.plot_mode(i, basis='char', **kwargs)Plot the shape of mode i (wave magnitude and phase along the edges).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| i | int | Mode index. | required |
| basis | str | Variable flavor (default "char"). |
'char' |
| **kwargs | Forwarded to :func:nefes.plotting.plot_mode_shape. |
{} |
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
plot_spectrum
perturbation.EigenmodeResult.plot_spectrum(**kwargs)Plot the spectrum: growth rate vs modal frequency, with the stability boundary.
The eigenvalues are markers in the (frequency, growth rate) plane (split about the growth = 0 stability line); the :attr:contour they were searched in is outlined so the searched complex-plane region is visible around the found modes. Pass contour=None to suppress the outline, or your own contour(s) to override. Forwards the rest to :func:nefes.plotting.plot_spectrum.
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
summary
perturbation.EigenmodeResult.summary()List of per-mode dicts: frequency (Hz), growth rate (1/s), damping ratio, residual.
Returns
| Name | Type | Description |
|---|---|---|
| list of dict | One entry per mode, ordered by frequency. |