perturbation.PerturbationBC

perturbation.PerturbationBC(
    kind='inherit',
    R=None,
    Z=None,
    specific=False,
    entropy_in=None,
    entropy_coupling=None,
    acoustic_to_entropy=None,
    driven=(),
    amplitudes=None,
)

Acoustic/perturbation closure for a single-port terminal node.

Build one with the named constructors (:meth:hard_wall, :meth:open_end, :meth:anechoic, :meth:reflection, :meth:impedance, :meth:mean_flow_open_end); :meth:inherit (the default) leaves the linearized mean boundary row untouched. Any of these accepts driven/amplitudes to additionally inject incoming waves.

Attributes

Name	Type	Description
kind	str	One of :data:`KINDS`.
R	(complex or callable or tuple, optional)	Reflection coefficient for `kind == "reflection"`.
Z	(complex or callable or tuple, optional)	Acoustic impedance for `kind == "impedance"` (specific if `specific`).
specific	bool	If True, `Z` is normalized by the characteristic impedance `rho c`.
entropy_in	(complex or callable or tuple, optional)	Incoming entropy-wave amplitude seated at an inflow terminal (default `0`). Shorthand for `driven=("entropy",)` with this amplitude; the two add if both set.
entropy_coupling	(complex or callable or tuple, optional)	Off-diagonal `R_s`: arriving entropy -> reflected acoustic at an outlet (entropy noise). Default `0`. Ignored at an inlet (entropy is to-specify).
acoustic_to_entropy	(complex or callable or tuple, optional)	Off-diagonal: arriving acoustic -> specified entropy at an inlet. Default `0`. Ignored at an outlet.
driven	tuple of str	Wave families injected at this boundary. `"acoustic"` and `"entropy"` (the :data:`DRIVABLE_FAMILIES`) plus, at a genuine inflow, any transported reacting scalar named in `prob.scalar_names` (a composition / equivalence-ratio wave) – scalar names are resolved at stamp time, since the BC has no problem context yet. Empty (the default) is a passive, unforced terminal. A family listed here drives a unit incoming wave unless `amplitudes` overrides it. A driven scalar convects and does radiate sound wherever the linearization is inherited (a flame, an area change, a resolved or inherited compact nozzle – the full Jacobian carries composition -> acoustic). The one place that coupling is dropped is a hand-written compact-nozzle closure (see :class:`~nefes.perturbation.response.forced.CompositionalNoiseWarning`).
amplitudes	(dict, optional)	Per-family complex amplitude (constant, table, or callable), keyed by a family in `driven`. Families in `driven` but absent here drive a unit wave.

Methods

Name	Description
acoustic_to_entropy_coefficient	Off-diagonal: arriving acoustic -> specified entropy at an inlet (0 unless set).
anechoic	Reflection-free termination (`R = 0`).
choked_nozzle	Compact (low-frequency) choked-nozzle outlet – Marble–Candel.
closure	Matrix closure `(A, b)` for one terminal at `freq` (Hz) and the mean state.
compact_nozzle	Alias of :meth:`choked_nozzle`.
constant_mass_flow	Constant-mass-flow outlet termination – pins `mdot' = 0` acoustically.
entropy_coupling_coefficient	Off-diagonal `R_s`: arriving entropy -> reflected acoustic at an outlet.
entropy_forcing	Entropy-row forcing at `freq` (Hz): the seated `entropy_in` plus any driven entropy wave.
forcing	Acoustic-row forcing `b` at `freq` (Hz): the driven acoustic wave (0 if none).
hard_wall	Rigid wall, `u' = 0` (`R = +1`).
impedance	Acoustic impedance `Z` (absolute Pa.s/m, or specific if `specific`).
impedance_polar	Impedance from a magnitude and phase (degrees); specific (`Z/rho c`) by default.
inherit	Keep the linearized mean boundary row (the default).
mean_flow_open_end	Convective open end, `R = -(1 - M)/(1 + M)` (`-1` at `M=0`).
open_end	Ideal pressure-release open end, `p' = 0` (`R = -1`).
reflection	Prescribed reflection coefficient `R` (constant, table, or callable).
reflection_coefficient	Acoustic reflection coefficient `R` at `freq` (Hz) and the terminal mean state.

acoustic_to_entropy_coefficient

perturbation.PerturbationBC.acoustic_to_entropy_coefficient(freq)

Off-diagonal: arriving acoustic -> specified entropy at an inlet (0 unless set).

anechoic

perturbation.PerturbationBC.anechoic(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Reflection-free termination (R = 0).

choked_nozzle

perturbation.PerturbationBC.choked_nozzle(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Compact (low-frequency) choked-nozzle outlet – Marble–Candel.

Enforces delta_M = 0 at the nozzle inlet (the duct outlet edge), so the reflected acoustic wave couples to the arriving entropy wave::

g = R f + R_s h,
R   = (2 - (gamma-1) M) / (2 + (gamma-1) M),
R_s = (c/rho) M / (2 + (gamma-1) M),

with M the outlet mean Mach. At M -> 0 this is a hard wall (R = +1, R_s = 0). Must terminate an outlet (entropy must be an arriving wave).

closure

perturbation.PerturbationBC.closure(
    freq,
    rho,
    c,
    u,
    M,
    specify,
    arriving,
    p=None,
)

Matrix closure (A, b) for one terminal at freq (Hz) and the mean state.

The closure is the linear law w[specify] = A @ w[arriving] + b: the waves the boundary must specify (those entering the domain) as a reflection A of the waves arriving from the interior, plus an injected forcing b. The scalar reflection sits on the acoustic-acoustic entry; the off-diagonals carry entropy <-> acoustic coupling.

Parameters

Name	Type	Description	Default
freq	float	Frequency (Hz) at which the coefficients are evaluated.	required
rho	float	Mean density, sound speed, and axial velocity at the terminal edge.	required
c	float	Mean density, sound speed, and axial velocity at the terminal edge.	required
u	float	Mean density, sound speed, and axial velocity at the terminal edge.	required
M	float	Outward-normal mean Mach number at the terminal.	required
specify	sequence of int	To-specify and arriving characteristic indices from :func:`matrices.partition`.	required
arriving	sequence of int	To-specify and arriving characteristic indices from :func:`matrices.partition`.	required
p	float	Mean static pressure; the `choked_nozzle` coefficients take the effective `gamma = rho c^2 / p` from it (required for that kind), consistent with any thermo backend.	`None`

Returns

Name	Type	Description
A	ndarray	Reflection matrix, shape `(len(specify), len(arriving))`.
b	ndarray	Forcing vector, length `len(specify)`.

compact_nozzle

perturbation.PerturbationBC.compact_nozzle(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Alias of :meth:choked_nozzle.

constant_mass_flow

perturbation.PerturbationBC.constant_mass_flow(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Constant-mass-flow outlet termination – pins mdot' = 0 acoustically.

The linearization of a fixed-mass-flow boundary: the unsteady mass flux vanishes, A(u rho' + rho u') = 0, which in characteristics is::

g = R f + R_s h,
R   = (1 + M) / (1 - M),
R_s = u / (rho (1 - M)) = c M / (rho (1 - M)),

with M the outlet mean Mach. At M -> 0 this is a hard wall (R = +1, R_s = 0). This is the closure a :func:~nefes.elements.catalog.mass_flow_outlet inherits automatically; use it to impose a constant-mass-flow termination on any other outlet (e.g. a choked upstream injector seen from downstream). Must terminate an outlet (entropy must be an arriving wave).

entropy_coupling_coefficient

perturbation.PerturbationBC.entropy_coupling_coefficient(
    freq,
    rho,
    c,
    M,
    p=None,
)

Off-diagonal R_s: arriving entropy -> reflected acoustic at an outlet.

Zero unless choked_nozzle (R_s = (c/rho) M/(2+(gamma-1)M)) or an explicit entropy_coupling carrier is set. M is the (outward-normal) mean Mach; the effective gamma is taken from the mean state (gamma = rho c^2 / p).

entropy_forcing

perturbation.PerturbationBC.entropy_forcing(freq)

Entropy-row forcing at freq (Hz): the seated entropy_in plus any driven entropy wave.

forcing

perturbation.PerturbationBC.forcing(freq)

Acoustic-row forcing b at freq (Hz): the driven acoustic wave (0 if none).

hard_wall

perturbation.PerturbationBC.hard_wall(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Rigid wall, u' = 0 (R = +1).

impedance

perturbation.PerturbationBC.impedance(
    Z,
    specific=False,
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Acoustic impedance Z (absolute Pa.s/m, or specific if specific).

impedance_polar

perturbation.PerturbationBC.impedance_polar(
    magnitude,
    phase_deg=0.0,
    specific=True,
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Impedance from a magnitude and phase (degrees); specific (Z/rho c) by default.

This is the closure the UI exposes: magnitude = 1, phase = 0 is the matched (anechoic) termination, and the rigid-wall limit is magnitude -> inf.

inherit

perturbation.PerturbationBC.inherit()

Keep the linearized mean boundary row (the default).

mean_flow_open_end

perturbation.PerturbationBC.mean_flow_open_end(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Convective open end, R = -(1 - M)/(1 + M) (-1 at M=0).

open_end

perturbation.PerturbationBC.open_end(
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Ideal pressure-release open end, p' = 0 (R = -1).

reflection

perturbation.PerturbationBC.reflection(
    R,
    entropy_coupling=None,
    entropy_in=None,
    driven=(),
    amplitudes=None,
)

Prescribed reflection coefficient R (constant, table, or callable).

entropy_coupling optionally adds the off-diagonal R_s (arriving entropy -> reflected acoustic) at an outlet, for a generic entropy-noise termination.

reflection_coefficient

perturbation.PerturbationBC.reflection_coefficient(freq, rho, c, M, p=None)

Acoustic reflection coefficient R at freq (Hz) and the terminal mean state.

Returns None for inherit (signalling “do not stamp this terminal”). M is the outward-normal mean Mach number at the terminal edge. The effective gamma for choked_nozzle is taken from the mean state (gamma = rho c^2 / p), so p (the mean static pressure) must be supplied for that kind – correct for any thermo backend (see :func:_gamma_minus_one).