Jacobians¶
Jacobians between flow variable sets.
Six five-component variable sets, each labelled by a single calligraphic letter, describe the same flow state; boundary conditions, the characteristic treatment and the mixing planes all need to move small perturbations between them:
primitive
\[\mathcal{P} = [\rho, V_x, V_r, V_\theta, p]^\mathrm{T}\]conserved – what
set_conserved()stores\[\mathcal{U} = [\rho, \rho V_x, \rho V_r, \rho r V_\theta, \rho e]^\mathrm{T}\]flux – the x-direction advective flux of each conserved variable
\[\mathcal{F} = [\rho V_x,\ \rho V_x^2 + p,\ \rho V_x V_r,\ \rho V_x r V_\theta,\ \rho V_x h_0]^\mathrm{T}\]chic – one-dimensional characteristic variables of the Euler equations
\[\mathcal{C} = [c_\mathrm{up}, c_\mathrm{down}, c_r, c_t, c_s]^\mathrm{T}\]bcond – what a subsonic inflow prescribes; see
InletPatch\[\mathcal{B} = [h_0, s, \tan\alpha, \sin\beta, p]^\mathrm{T}\]mix – what a mixing plane exchanges; see
MixingPatch\[\mathcal{M} = [h_0, s, V_r, V_\theta, p]^\mathrm{T}\]
Every function below is named X_to_Y and returns the Jacobian
\(\mathbf{J}_{\mathcal{X}\to\mathcal{Y}}\), evaluated pointwise from a
Block’s current state and returned as a batch of 5x5
matrices stacked on the trailing two axes:
Two conventions keep this cheap. First, whenever both a Jacobian and its
inverse are needed, the inverse is not obtained by numerically inverting the
forward 5x5 matrix at every point – it is worked out analytically in closed
form and implemented as its own function. conserved_to_primitive(),
for instance, is the closed-form inverse of primitive_to_conserved(),
and every other Y_to_X in this module pairs with an X_to_Y the same
way. Second, every Jacobian between two sets neither of which is primitive
necessarily passes through primitive variables,
\(\mathbf{J}_{\mathcal{X}\to\mathcal{Y}} = \mathbf{J}_{\mathcal{P}\to\mathcal{Y}}\,\mathbf{J}_{\mathcal{X}\to\mathcal{P}}\),
and where that composite sits on a hot path – the characteristic and
mixing-plane boundary conditions evaluate one every timestep – the product
is worked out analytically once and implemented as its own fused function
rather than composed from two separate calls. For example
chic_to_bcond() evaluates
\(\mathbf{J}_{\mathcal{C}\to\mathcal{B}} = \mathbf{J}_{\mathcal{P}\to\mathcal{B}}\,\mathbf{J}_{\mathcal{C}\to\mathcal{P}}\)
directly, rather than calling primitive_to_bcond() and
chic_to_primitive() and multiplying the results at every timestep.
Elsewhere, where the extra multiply is not performance-critical, a composite
Jacobian is simply the product of two separately evaluated calls –
flux_to_conserved() and conserved_to_flux(), for instance, are
literally primitive_to_conserved() \(\cdot\) flux_to_primitive()
and primitive_to_flux() \(\cdot\) conserved_to_primitive()
multiplied together at call time.
All Jacobians are evaluated in the nondimensional space the block stores its
state in, using conserved_nd,
r_nd and the fluid’s _nd thermodynamic
derivative properties.
- perturbation.primitive_to_conserved(block, out=None)[source]¶
Jacobian of conserved variables with respect to primitive variables.
\[\delta\mathcal{U} = \mathbf{J}_{\mathcal{P}\to\mathcal{U}}\,\delta\mathcal{P}\]
- perturbation.conserved_to_primitive(block)[source]¶
Jacobian of primitive variables with respect to conserved variables.
Analytical inverse of
primitive_to_conserved().
- perturbation.primitive_to_chic(block, out=None)[source]¶
Jacobian of one-dimensional characteristic variables with respect to primitive variables.
- perturbation.chic_to_primitive(block, out=None)[source]¶
Jacobian of primitive variables with respect to one-dimensional characteristic variables.
Analytical inverse of
primitive_to_chic().
- perturbation.primitive_to_flux(block)[source]¶
Jacobian of the x-direction advective flux with respect to primitive variables.
- perturbation.flux_to_primitive(block, out=None)[source]¶
Jacobian of primitive variables with respect to the x-direction advective flux.
Analytical inverse of
primitive_to_flux().
- perturbation.primitive_to_bcond(block, out=None)[source]¶
Jacobian of a subsonic inflow’s prescribed quantities with respect to primitive variables.
Both angles are measured against the meridional velocity magnitude \(V_m = \sqrt{V_x^2 + V_r^2}\), as in
tanAlphaandsinBeta, so every angle derivative below carries \(V_m\) and not the total speed.sinBetais used in place oftanBetato avoid the singularity at \(\beta = 90^\circ\); \(\sin\beta = V_r/V_m\), with derivatives verified numerically.
- perturbation.bcond_to_primitive(block, out=None)[source]¶
Jacobian of primitive variables with respect to a subsonic inflow’s prescribed quantities.
Analytical inverse of
primitive_to_bcond().\(V_m\) is the meridional speed the two angles are measured against and \(V^2 = V_m^2 + V_\theta^2\) the total speed squared. The entropy row of the forward matrix eliminates \(\delta\rho\) in favour of \(\delta s\) and \(\delta p\), leaving a stagnation-enthalpy residual
\[\delta b_0 = \delta h_0 - \frac{\partial h_0/\partial\rho|_p}{\partial s/\partial\rho|_p}\,\delta s + \text{cross}\cdot\delta p\]Substituting that into the enthalpy row leaves the meridional velocity projection \(\delta u = V_x\,\delta V_x + V_r\,\delta V_r\) as the only remaining unknown, solved for as
\[\delta u = \frac{V_m^2}{V^2} \left(\delta b_0 - V_\theta V_m\,\delta\tan\alpha\right)\]which is then split between \(\delta V_x\) and \(\delta V_r\) using \(\delta\sin\beta\).
- perturbation.primitive_to_mix(block, out=None)[source]¶
Jacobian of a mixing plane’s exchanged quantities with respect to primitive variables.
- perturbation.mix_to_primitive(block, out=None)[source]¶
Jacobian of primitive variables with respect to a mixing plane’s exchanged quantities.
Analytical inverse of
primitive_to_mix().
- perturbation.mix_to_conserved(block, out=None)[source]¶
Jacobian of conserved variables with respect to a mixing plane’s exchanged quantities.
Analytically fused product \(\mathbf{J}_{\mathcal{M}\to\mathcal{U}} = \mathbf{J}_{\mathcal{P}\to\mathcal{U}}\,\mathbf{J}_{\mathcal{M}\to\mathcal{P}}\), i.e.
primitive_to_conserved()\(\cdot\)mix_to_primitive(), rather than composing the two Jacobians at call time.
- perturbation.chic_to_bcond(block, out=None)[source]¶
Jacobian of a subsonic inflow’s prescribed quantities with respect to characteristic variables.
Analytically fused product \(\mathbf{J}_{\mathcal{C}\to\mathcal{B}} = \mathbf{J}_{\mathcal{P}\to\mathcal{B}}\,\mathbf{J}_{\mathcal{C}\to\mathcal{P}}\), i.e.
primitive_to_bcond()\(\cdot\)chic_to_primitive(). Rows 0-3 against the four incoming characteristic columns form the square system a non-reflecting inlet solves to drive its boundary condition residuals to zero; seeInletPatch. The angle derivatives are as inprimitive_to_bcond(), both measured against the meridional speed.
- perturbation.chic_to_mix(block, out=None)[source]¶
Jacobian of a mixing plane’s exchanged quantities with respect to characteristic variables.
Analytically fused product \(\mathbf{J}_{\mathcal{C}\to\mathcal{M}} = \mathbf{J}_{\mathcal{P}\to\mathcal{M}}\,\mathbf{J}_{\mathcal{C}\to\mathcal{P}}\), i.e.
primitive_to_mix()\(\cdot\)chic_to_primitive().
- perturbation.flux_to_conserved(block)[source]¶
Jacobian of conserved variables with respect to the x-direction advective flux.
Computed as
primitive_to_conserved()\(\cdot\)flux_to_primitive().
- perturbation.conserved_to_flux(block)[source]¶
Jacobian of the x-direction advective flux with respect to conserved variables.
Computed as
primitive_to_flux()\(\cdot\)conserved_to_primitive().