Classes
class	GasState
class	DampingCoeffs

Functions
bool	_is_longitudinal (Optional[str] mode_name)
Dict[str, float]	damping_budget (float f_hz, float D_ch, float L_ch, GasState gas, Optional[DampingCoeffs] coeffs=None, Optional[str] mode_name=None)
float	mode_driving_rate (float f_hz, float gamma, float overlap, float n, float tau_sens)
float	mode_driving_rate_max (float f_hz, float gamma, float overlap, float n)
float	_ratio (float num, float den)
Dict[str, float]	mode_growth_rate (float f_hz, str mode_name, float D_ch, float L_ch, GasState gas, *, float n, float tau_sens, Optional[float] overlap=None, Optional[DampingCoeffs] coeffs=None)
Dict[str, float]	_mode_frequencies (GasState gas, float L_ch, float D_ch, int n_long)
Dict[str, object]	analyze_acoustic_modes (float D_ch, float L_ch, GasState gas, *, float n, float tau_sens, Optional[DampingCoeffs] coeffs=None, int n_long=3)
Dict[str, float]	fast_acoustic (float D_ch, float L_ch, GasState gas, *, float n, float tau_sens, Optional[DampingCoeffs] coeffs=None)

Variables
dict	DEFAULT_OVERLAP

Detailed Description

High-frequency (acoustic / "screech") stability: per-mode growth rate.

Implements the modal growth-rate balance [Phys §4.2, eq 4.1] as a **lumped, normalized** design-guidance
model (we do not have spatial mode shapes / heat-release fields in Layer 1, so the mode-shape/heat-
release overlap is a documented per-mode factor, not an integral):

    alpha_mode = alpha_drive - alpha_damp

    alpha_drive = (omega/2) * (gamma-1) * overlap * Re[ n*(1 - e^{-i*omega*tau_sens}) ]
                = (omega/2) * (gamma-1) * overlap * n * (1 - cos(omega * tau_sens))  [Phys §2, §4.2]

    alpha_damp  = alpha_nozzle + alpha_viscous + alpha_injector + alpha_twophase     (itemized budget)

A mode **grows** when alpha_mode > 0. The driving is the part of the n-tau response IN PHASE with p'
(Rayleigh): n(1 - cos omega*tau) >= 0, largest at omega*tau = pi and zero at 2*pi -- Crocco's
stability bucket (Harrje & Reardon SP-194 ch. 4). The quadrature part n*sin(omega*tau) shifts the
frequency and does no work; this module used to take it, which booked combustion as DAMPING over
half of every period of omega*tau.

Two margins per mode, both 1 at neutral stability:
  * ``margin``             = damping / driving at the model's tau_sens (nominal phase);
  * ``margin_worst_phase`` = damping / driving at omega*tau = pi = n_min / n, Crocco's interaction-
    index margin, independent of tau.

Why the verdict is report-only by default (analysis.py): omega*tau_sens is tens of radians (1T ~ 29
rad on the 6500 N) and tau_sens = chi*tau_vap with chi uncalibrated, so the nominal-phase margin
flips with a few percent of tau; the worst-phase margin is set by gamma, n, the overlap and the
injector/two-phase fractions, none of which the design moves. Harrje & Reardon rate HF stability by
test (bomb / pulse, >= 25 kHz Pc), and so does this tool until T7/H3 calibrate the damping.

Pure numeric module — params in as scalars/dataclasses; integration (config -> params) lives in analysis.py.

Function Documentation

◆ _is_longitudinal()

bool engine.pipeline.stability.acoustic._is_longitudinal ( Optional[str] mode_name )

protected

Pure axial mode ("1L", "2L", ...). Anything else is transverse or mixed.

Definition at line 72 of file acoustic.py.

Referenced by damping_budget().

◆ _mode_frequencies()

Dict[str, float] engine.pipeline.stability.acoustic._mode_frequencies	(	GasState	gas,
		float	L_ch,
		float	D_ch,
		int	n_long )

protected

Definition at line 157 of file acoustic.py.

Referenced by analyze_acoustic_modes().

◆ _ratio()

float engine.pipeline.stability.acoustic._ratio	(	float	num,
		float	den )

protected

damping/driving; no driving -> infinite margin.

Definition at line 120 of file acoustic.py.

Referenced by mode_growth_rate().

◆ analyze_acoustic_modes()

Dict[str, object] engine.pipeline.stability.acoustic.analyze_acoustic_modes	(	float	D_ch,
		float	L_ch,
		GasState	gas,
		*	,
		float	n,
		float	tau_sens,
		Optional[DampingCoeffs]	coeffs = None,
		int	n_long = 3 )

Rich acoustic analysis: growth rate + damping budget for every mode (1L..3L, 1T, 2T, 1R, 3T...).

Returns ``{"modes": [per-mode dicts sorted by alpha desc], "limiting_mode": name, "any_unstable": bool}``.
[Phys §4.2 — feeds viz #2 (damping bars), #3 (frequency ladder), #4 (phase clock)]

Definition at line 165 of file acoustic.py.

References _mode_frequencies(), and mode_growth_rate().

◆ damping_budget()

Dict[str, float] engine.pipeline.stability.acoustic.damping_budget	(	float	f_hz,
		float	D_ch,
		float	L_ch,
		GasState	gas,
		Optional[DampingCoeffs]	coeffs = None,
		Optional[str]	mode_name = None )

Itemized acoustic damping rates [1/s] for a mode at frequency ``f_hz``.  [Phys §4.2 — viz #2]

Keys: ``nozzle``, ``viscous``, ``injector``, ``twophase``, ``total``. All >= 0 (damping).
``mode_name`` sets the nozzle-plane weight (longitudinal 1, transverse 1/2; None = longitudinal).

Definition at line 81 of file acoustic.py.

References _is_longitudinal().

Referenced by mode_growth_rate().

◆ fast_acoustic()

Dict[str, float] engine.pipeline.stability.acoustic.fast_acoustic	(	float	D_ch,
		float	L_ch,
		GasState	gas,
		*	,
		float	n,
		float	tau_sens,
		Optional[DampingCoeffs]	coeffs = None )

Fast acoustic check for the Layer-1 loop: only 1L and 1T (the usual first offenders).

Returns ``alpha_max``, ``limiting_mode``, ``stable``, ``f_1L``, ``f_1T``, and the smallest
``margin`` (nominal phase) and ``margin_worst_phase`` over the two modes, each with the mode
that sets it.

Definition at line 189 of file acoustic.py.

References max, min, and mode_growth_rate().

◆ mode_driving_rate()

float engine.pipeline.stability.acoustic.mode_driving_rate	(	float	f_hz,
		float	gamma,
		float	overlap,
		float	n,
		float	tau_sens )

Combustion driving rate [1/s]: (omega/2)(gamma-1)*overlap*n*(1 - cos(omega*tau_sens)).

Rayleigh: the part of the n-tau response in phase with p', ``Re[core.n_tau_gain]``. >= 0.

Definition at line 105 of file acoustic.py.

Referenced by mode_growth_rate().

◆ mode_driving_rate_max()

float engine.pipeline.stability.acoustic.mode_driving_rate_max	(	float	f_hz,
		float	gamma,
		float	overlap,
		float	n )

Largest driving any lag can give [1/s]: omega*tau = pi, ``omega*(gamma-1)*overlap*n``.

Definition at line 115 of file acoustic.py.

Referenced by mode_growth_rate().

◆ mode_growth_rate()

Dict[str, float] engine.pipeline.stability.acoustic.mode_growth_rate	(	float	f_hz,
		str	mode_name,
		float	D_ch,
		float	L_ch,
		GasState	gas,
		*	,
		float	n,
		float	tau_sens,
		Optional[float]	overlap = None,
		Optional[DampingCoeffs]	coeffs = None )

Net growth rate for one acoustic mode, with its damping budget and margins.

``alpha = driving - damping_total``; **stable if alpha < 0**.  [Phys §4.2, eq 4.1]
``margin`` = damping/driving at tau_sens; ``margin_worst_phase`` = damping/driving at
omega*tau = pi (= n_min/n). Both > 1 is stable; ``n_min`` is the interaction index at which the
mode goes neutral at the worst phase.

Definition at line 125 of file acoustic.py.

References _ratio(), damping_budget(), mode_driving_rate(), and mode_driving_rate_max().

Referenced by analyze_acoustic_modes(), and fast_acoustic().

Variable Documentation

◆ DEFAULT_OVERLAP

dict engine.pipeline.stability.acoustic.DEFAULT_OVERLAP

Initial value:

=  {
    "1L": 0.70, "2L": 0.45, "3L": 0.30,
    "1T": 0.40, "2T": 0.30, "1R": 0.35, "3T": 0.25, "1T1R": 0.25,
}

Definition at line 47 of file acoustic.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _is_longitudinal()

◆ _mode_frequencies()

◆ _ratio()

◆ analyze_acoustic_modes()

◆ damping_budget()

◆ fast_acoustic()

◆ mode_driving_rate()

◆ mode_driving_rate_max()

◆ mode_growth_rate()

Variable Documentation

◆ DEFAULT_OVERLAP