params.py

Go to the documentation of this file.

"""Config -> flat scalar state, in pure Python (no C dependency).
 
WHY THIS EXISTS
    The Numba kernels used to read their inputs out of the C `EdEngineState`
    struct (numba_eval.extract_params called native_injector.build_state), so
    Numba could not run without the C library loaded. That made the C port
    impossible to delete. This module reproduces that reconciliation with no
    ctypes involved.
 
WHY IT IS A TRANSCRIPTION, NOT A REWRITE
    `native_injector.build_state` encodes decisions that are NOT recoverable by
    reading the config schema -- see the inline notes on smd_model and
    we_corr_max below. Re-deriving "what the config means" from the YAML would
    silently produce different numbers on some configs. So each field here is a
    line-for-line transcription of the corresponding `_fill_*` helper, and
    tests/test_accel_params_match_native_state.py asserts exact equality against
    the real EdEngineState for every committed config while the C port still
    exists to compare against.
 
The returned object mirrors EdEngineState's attribute paths exactly
(`st.fluid_O.density`, `st.injector.imp_O.d_jet`, ...) so the existing
param-vector mapping reads from either interchangeably.
"""
from __future__ import annotations
 
import numpy as np
from operator import attrgetter as _attrgetter
from types import SimpleNamespace
 
from engine.core.injectors.layout import effective_discharge
 
# Enum mappings -- mirror native_injector._PHI / _INJ / _EFF_MODEL.
_PHI = {"none": 0, "sqrtP": 1, "logP": 2}
_INJ = {"pintle": 0, "impinging": 1, "coaxial": 2}
_EFF_MODEL = {"constant": 0, "linear": 1, "exponential": 2}
 
 
def _ns(**kw):
    return SimpleNamespace(**kw)
 
 
def _discharge(c):
    # (resolved by engine.core.injectors.layout.effective_discharge before it gets here)
    """Mirrors native_injector._fill_discharge.
 
    When the config declares an orifice INLET geometry, resolve it here and hand the kernel
    the finished Cd_inf with the diameter scaling switched OFF. The kernel has no notion of
    inlet treatment, so passing the raw Cd_inf would leave it on the old diameter path while
    Python used the inlet value -- a fresh Python/kernel divergence of exactly the kind that
    the x_star evaporation split already cost this codebase 9.7% of thrust.
    """
    from engine.core.discharge import cd_inf_from_inlet_geometry, lichtarowicz_re_inputs
    _cd_inlet = cd_inf_from_inlet_geometry(c)
    _lich = lichtarowicz_re_inputs(c)
    _lod, _beta, _cdu = (0.0, 0.0, 0.0) if _lich is None else (
        _lich[1], float(_lich[2] or 0.0), _lich[0])
    _cd_inf = float(_cd_inlet) if _cd_inlet is not None else float(c.Cd_inf)
    _use_geom = 0 if _cd_inlet is not None else int(bool(c.use_geometry_cd))
    return _ns(
        Cd_inf=_cd_inf, a_Re=float(c.a_Re), Cd_min=float(c.Cd_min),
        use_geometry_cd=_use_geom,
        d_ref_m=float(c.d_ref_m), d_min_m=float(c.d_min_m),
        cd_small_hole_exponent=float(c.cd_small_hole_exponent),
        cd_large_hole_log_gain=float(c.cd_large_hole_log_gain),
        cd_inf_max=float(c.cd_inf_max), cd_inf_min_geom=float(c.cd_inf_min_geom),
        use_pressure_correction=int(bool(c.use_pressure_correction)),
        P_ref=float(c.P_ref), a_P=float(c.a_P),
        use_temperature_correction=int(bool(c.use_temperature_correction)),
        T_ref=float(c.T_ref), a_T=float(c.a_T),
        lich_l_over_d=_lod, lich_beta=_beta, lich_cd_u=_cdu,
    )
 
 
def _feed_fittings_K(c):
    from engine.pipeline.feed_loss import fittings_K
    return fittings_K(c)
 
 
def _feed(c):
    """Mirrors native_injector._fill_feed."""
    return _ns(
        d_inlet=float(getattr(c, "d_inlet", 0.0) or 0.0),
        A_hydraulic=float(getattr(c, "A_hydraulic", 0.0) or 0.0),
        # Itemised fittings add to K0 on the line velocity head (feed_loss.fittings_K, same
        # summation order); no fittings => K0 exactly. roughness_m configs never get here
        # (accel.can_handle hands them to Python).
        K0=(float(c.K0) + _feed_fittings_K(c)) if getattr(c, "fittings", None) else float(c.K0),
        K1=float(c.K1), phi_type=_PHI[c.phi_type],
        # Exit dump into the manifold (feed_loss.delta_p_feed): same falsy reads as Python.
        K_exit=float(getattr(c, "K_exit", 0.0) or 0.0),
        d_exit=float(getattr(c, "d_exit", None) or 0.0),
    )
 
 
def _cav(config):
    """Vena-contracta Cc per stream for the Nurick cavitation limit (discharge.contraction_coefficient)."""
    from engine.core.discharge import contraction_coefficient, inlet_radius_ratio_of
    from engine.core.injectors.layout import effective_discharge
    return _ns(cc_O=contraction_coefficient(inlet_radius_ratio_of(effective_discharge(config, "oxidizer"))),
               cc_F=contraction_coefficient(inlet_radius_ratio_of(effective_discharge(config, "fuel"))))
 
 
def _fluid(f):
    """Mirrors native_injector._fill_fluid.
 
    Note the `or` defaults: a missing OR zero temperature becomes 0.0, and a
    missing OR zero latent_heat becomes 300e3. Falsy checks, not `is None`.
    """
    return _ns(
        density=float(f.density), viscosity=float(f.viscosity),
        surface_tension=float(f.surface_tension),
        temperature=float(getattr(f, "temperature", 0.0) or 0.0),
        latent_heat=float(getattr(f, "latent_heat", 300e3) or 300e3),
        # Boiling point feeds the Spalding transfer number B_M in the derived evaporation
        # constant. 0 => the kernel falls back to the legacy fixed-K path for that stream.
        boiling_point=float(getattr(f, "boiling_point", 0.0) or 0.0),
        # Cavitation limit (impinging._stream_flow): vapour pressure; NaN => no limit.
        vapor_pressure=(float(f.vapor_pressure) if getattr(f, "vapor_pressure", None) is not None
                        else float("nan")),
    )
 
 
def _comb(eff):
    """Mirrors native_injector._fill_comb."""
    floor = getattr(eff, "tau_Tc_floor_K", None)
    ropt = getattr(eff, "R_opt", None)
    return _ns(
        model=_EFF_MODEL.get(eff.model, 2),
        C=float(eff.C), K=float(eff.K),
        cooling_efficiency_floor=float(eff.cooling_efficiency_floor),
        use_cooling_coupling=int(bool(eff.use_cooling_coupling)),
        tau_ref=float(eff.tau_ref), tau_ref_P=float(eff.tau_ref_P),
        tau_ref_T=float(eff.tau_ref_T), n_pressure=float(eff.n_pressure),
        T_star_fuel_cap_K=float(getattr(eff, "T_star_fuel_cap_K", 1000.0)),
        has_tau_Tc_floor=int(floor is not None),
        tau_Tc_floor=float(floor or 0.0),
        # Rupe momentum-ratio mixing; R_opt<=0 => derive from impingement angles.
        Em_peak=float(getattr(eff, "Em_peak", 0.96)),
        mixing_sigma=float(getattr(eff, "mixing_sigma", 1.5)),
        R_opt=float(ropt) if ropt is not None else 0.0,
    )
 
 
def _cooling(cfg):
    """Mirrors native_injector._fill_cooling.
 
    The C struct is zero-initialised, so fields guarded by `if rg is not None` /
    `if ab is not None` stay 0.0 when that config block is absent. The defaults
    below reproduce that -- do not "improve" them into schema defaults.
    """
    rg, ab = cfg.regen_cooling, cfg.ablative_cooling
    fc = getattr(cfg, "film_cooling", None)
    eff = cfg.combustion.efficiency
    c = _ns(
        regen_enabled=int(bool(rg and rg.enabled)),
        film_enabled=int(bool(fc and fc.enabled)),
        ablative_enabled=int(bool(ab and ab.enabled)),
        graphite_enabled=int(bool(getattr(cfg, "graphite_insert", None)
                                  and cfg.graphite_insert.enabled)),
        use_cooling_coupling=int(bool(eff.use_cooling_coupling)),
        cooling_efficiency_floor=float(eff.cooling_efficiency_floor),
        # zero-init defaults for the two optional blocks
        hot_gas_viscosity=0.0, hot_gas_thermal_conductivity=0.0,
        hot_gas_prandtl=0.0, gas_turbulence_intensity=0.0, recovery_factor=0.0,
        radiation_emissivity_hot=0.0, radiation_view_factor=0.0,
        regen_chamber_inner_diameter=0.0,
        ablative_coverage_fraction=0.0, ablative_surface_temperature_limit=0.0,
        ablative_material_density=0.0, ablative_heat_of_ablation=0.0,
        ablative_specific_heat=0.0, ablative_pyrolysis_temperature=0.0,
        ablative_use_physics_based_blowing=0, ablative_blowing_efficiency=0.0,
        ablative_blowing_coefficient=0.0, ablative_blowing_min_reduction_factor=0.0,
        ablative_turbulence_reference_intensity=0.0, ablative_turbulence_sensitivity=0.0,
        ablative_turbulence_exponent=0.0, ablative_turbulence_max_multiplier=0.0,
        ablative_surface_emissivity=0.0, ablative_ambient_temperature=0.0,
        ablative_radiative_sink_minimum_threshold=0.0,
        ablative_radiative_sink_fallback_temperature=0.0,
    )
    if rg is not None:
        c.hot_gas_viscosity = float(rg.hot_gas_viscosity)
        c.hot_gas_thermal_conductivity = float(rg.hot_gas_thermal_conductivity)
        c.hot_gas_prandtl = float(rg.hot_gas_prandtl)
        c.gas_turbulence_intensity = float(rg.gas_turbulence_intensity)
        c.recovery_factor = float(rg.recovery_factor) if rg.recovery_factor is not None else 0.94
        c.radiation_emissivity_hot = float(rg.radiation_emissivity_hot)
        c.radiation_view_factor = float(rg.radiation_view_factor)
        c.regen_chamber_inner_diameter = float(rg.chamber_inner_diameter or 0.0)
    if ab is not None:
        c.ablative_coverage_fraction = float(ab.coverage_fraction)
        c.ablative_surface_temperature_limit = float(ab.surface_temperature_limit)
        c.ablative_material_density = float(ab.material_density)
        c.ablative_heat_of_ablation = float(ab.heat_of_ablation)
        c.ablative_specific_heat = float(ab.specific_heat)
        c.ablative_pyrolysis_temperature = float(ab.pyrolysis_temperature)
        c.ablative_use_physics_based_blowing = int(bool(ab.use_physics_based_blowing))
        c.ablative_blowing_efficiency = float(ab.blowing_efficiency)
        c.ablative_blowing_coefficient = float(ab.blowing_coefficient)
        c.ablative_blowing_min_reduction_factor = float(ab.blowing_min_reduction_factor)
        c.ablative_turbulence_reference_intensity = float(ab.turbulence_reference_intensity)
        c.ablative_turbulence_sensitivity = float(ab.turbulence_sensitivity)
        c.ablative_turbulence_exponent = float(ab.turbulence_exponent)
        c.ablative_turbulence_max_multiplier = float(ab.turbulence_max_multiplier)
        c.ablative_surface_emissivity = float(ab.surface_emissivity)
        c.ablative_ambient_temperature = float(ab.ambient_temperature)
        c.ablative_radiative_sink_minimum_threshold = float(ab.radiative_sink_minimum_threshold)
        c.ablative_radiative_sink_fallback_temperature = float(ab.radiative_sink_fallback_temperature)
    return c
 
 
def _geom(cg):
    """Mirrors native_injector._fill_geom. `cg` must come from ensure_chamber_geometry."""
    return _ns(
        A_throat=float(cg.A_throat), A_exit=float(cg.A_exit), volume=float(cg.volume),
        Lstar=float(cg.Lstar) if cg.Lstar else 0.0,
        length=float(cg.length),
        length_cylindrical=float(cg.length_cylindrical or 0.0),
        length_contraction=float(cg.length_contraction or 0.0),
        chamber_diameter=float(cg.chamber_diameter or 0.0),
        exit_diameter=float(cg.exit_diameter or 0.0),
        expansion_ratio=float(cg.expansion_ratio),
        nozzle_efficiency=float(cg.nozzle_efficiency),
        Cf=float(cg.Cf or 0.0),
        design_pressure=float(cg.design_pressure or 0.0),
    )
 
 
def _pintle(geom):
    """Pintle geometry, flattened.
 
    The area/hydraulic-diameter maths lives in engine.core.geometry and is called
    HERE, at the boundary, so the kernel sees scalars and the two implementations
    cannot drift on geometry.
    """
    from engine.core.geometry import get_effective_areas, get_hydraulic_diameters
    A_O, A_F = get_effective_areas(geom)
    dh_O, dh_F = get_hydraulic_diameters(geom)
    return _ns(A_O=float(A_O), A_F=float(A_F),
               d_hyd_O=float(dh_O), d_hyd_F=float(dh_F),
               d_orifice=float(geom.lox.d_orifice),
               h_gap=float(geom.fuel.h_gap),
               d_pintle_tip=float(geom.fuel.d_pintle_tip))
 
 
_PIN_ZERO = _ns(A_O=0.0, A_F=0.0, d_hyd_O=0.0, d_hyd_F=0.0, d_orifice=0.0, h_gap=0.0,
                d_pintle_tip=0.0)
 
 
def _imp(b):
    """Mirrors native_injector._fill_imp."""
    return _ns(
        n_elements=int(b.n_elements), d_jet=float(b.d_jet),
        impingement_angle=float(b.impingement_angle),
        spacing=float(getattr(b, "spacing", 0.0) or 0.0),
    )
 
 
_NET_ZERO = _ns(enabled=0, n_ports=0, h=0, A_ch=0.0, D_h=0.0, s=0.0, eps=0.0, scale=0.0,
                A_hole=0.0, d_hole=0.0, K_ent=0.0, C_R=0.0)
 
 
def _net(config, side):
    """The stream's back-channel ring (impinging._RingManifold), read off the very object the
    Python injector builds, so the kernel marches the same branch; zeros for a plenum."""
    from engine.core.injectors.impinging import _ring_manifold_for
    fl = config.fluids[side]
    b = getattr(config.injector.geometry, side)
    net = _ring_manifold_for(config, side, float(fl.density), float(fl.viscosity),
                             b.n_elements, b.d_jet)
    if net is None:
        return _NET_ZERO
    return _ns(enabled=1, n_ports=int(net.n_ports), h=int(net.h), A_ch=float(net.A_ch),
               D_h=float(net.D_h), s=float(net.s), eps=float(net.eps), scale=float(net.scale),
               A_hole=float(net.A_hole), d_hole=float(net.d_hole), K_ent=float(net.K_ent),
               C_R=float(net.C_R))
 
 
def build_state(config):
    """Pure-Python equivalent of native_injector.build_state.
 
    Returns a namespace with EdEngineState's attribute paths. Raises the same way
    build_state does on a config it cannot map (e.g. a pintle config, whose
    injector geometry has no .oxidizer/.fuel impinging branches).
    """
    from engine.pipeline.config_schemas import ensure_chamber_geometry
 
    g = config.injector.geometry
    sp = config.spray
    inj_type = _INJ[config.injector.type]
 
    # Only one geometry block is populated; the other stays zero. The kernels
    # branch on injector.type, so the unused half is never read.
    if inj_type == _INJ["impinging"]:
        imp_O, imp_F, pin = _imp(g.oxidizer), _imp(g.fuel), _PIN_ZERO
        net_O, net_F = _net(config, "oxidizer"), _net(config, "fuel")
    elif inj_type == _INJ["pintle"]:
        _z = _ns(n_elements=0, d_jet=0.0, impingement_angle=0.0, spacing=0.0)
        imp_O, imp_F, pin = _z, _z, _pintle(g)
        net_O = net_F = _NET_ZERO
    else:
        raise NotImplementedError(f"injector type {config.injector.type!r} not ported")
 
    spray = _ns(
        # Impinging atomization is ALWAYS Ingebo (see impinging.py); a stale
        # `lefebvre` in YAML is deliberately ignored. Reading spray.smd.model
        # here instead would change results on configs that carry the stale key.
        smd_model=1,
        smd_C=float(sp.smd.C), smd_m=float(sp.smd.m), smd_p=float(sp.smd.p),
        smd_scale=float(getattr(sp.smd, "smd_scale", 1.0) or 1.0),
        smd_property_scaling=float(bool(getattr(sp.smd, "smd_property_scaling", True))),
        # Falsy check, not `is None`: we_corr_max of 0.0 and null both -> 0.0.
        smd_we_corr_max=float(getattr(sp.smd, "we_corr_max", None))
        if getattr(sp.smd, "we_corr_max", None) else 0.0,
        use_turbulence_corrections=int(bool(getattr(sp, "use_turbulence_corrections", False))),
        turbulence_penetration_gain=float(getattr(sp, "turbulence_penetration_gain", 0.0) or 0.0),
        pintle_C=float(sp.pintle.C), pintle_B=float(sp.pintle.B),
        pintle_n=float(sp.pintle.n), pintle_p=float(sp.pintle.p),
        chamber_gas_R=float(sp.smd.chamber_gas_R),
        chamber_gas_T=float(sp.smd.chamber_gas_T),
        spray_angle_model=0 if sp.spray_angle.model == "J" else 1,
        spray_angle_k=float(sp.spray_angle.k), spray_angle_n=float(sp.spray_angle.n),
        we_min=float(sp.weber.get("We_min", 15.0)),
        evap_K=float(sp.evaporation.K),
        evap_x_star_limit=float(sp.evaporation.x_star_limit),
        evap_use_constraint=int(bool(sp.evaporation.use_constraint)),
        evap_model_code=1 if getattr(sp.evaporation, "model", "derived") == "derived" else 0,
        evap_C_evap=float(getattr(sp.evaporation, "C_evap", 1.562)),
        evap_cp_gas=float(getattr(sp.evaporation, "cp_gas", 2200.0)),
        evap_apply_tau_res=1.0 if getattr(sp.evaporation, "apply_tau_res_correction", False) else 0.0,
        # measurements.d32_*_um (impinging.py replaces the TN 4222 D32 where it was measured)
        d32_measured_O=float(getattr(sp.smd, "d32_measured_O", None) or 0.0),
        d32_measured_F=float(getattr(sp.smd, "d32_measured_F", None) or 0.0),
    )
 
    solver = _ns(
        closure_max_iterations=int(config.solver.closure.max_iterations),
        closure_Cd_reduction_factor=float(config.solver.closure.Cd_reduction_factor),
        Pc_min_bound=float(config.solver.Pc_bounds[0]),
        Pc_max_bound=float(config.solver.Pc_bounds[1]),
        tolerance=float(config.solver.tolerance),
        max_iterations=int(config.solver.max_iterations),
    )
 
    return _ns(
        injector=_ns(type=inj_type, imp_O=imp_O, imp_F=imp_F),
        pin=pin,
        net_O=net_O, net_F=net_F,
        # Same resolution the Python injector uses, so Cd cannot diverge between the paths.
        discharge_O=_discharge(effective_discharge(config, "oxidizer")),
        discharge_F=_discharge(effective_discharge(config, "fuel")),
        cav=_cav(config),
        feed_O=_feed(config.feed_system["oxidizer"]),
        feed_F=_feed(config.feed_system["fuel"]),
        fluid_O=_fluid(config.fluids["oxidizer"]),
        fluid_F=_fluid(config.fluids["fuel"]),
        spray=spray,
        solver=solver,
        comb=_comb(config.combustion.efficiency),
        cooling=_cooling(config),
        geom=_geom(ensure_chamber_geometry(config)),
    )
 
 
# ---------------------------------------------------------------------------
# Parameter-vector layout
#
# The kernels take one flat float64 array rather than a struct, so every scalar
# needs a stable index. _NAMES is that layout and the single source of truth for
# it; kernels.py pulls these names into its module globals so @njit code can use
# them as compile-time constants (P[G_AT] and friends).
#
# APPEND ONLY. Inserting a name shifts every index after it, which silently
# invalidates the cached .nbc artifacts compiled against the old layout.
# ---------------------------------------------------------------------------
# ---- parameter vector layout (mirrors the fields the C residual reads) -------
_NAMES = [
    # fluids
    "RHO_O", "MU_O", "SIG_O", "T_O",
    "RHO_F", "MU_F", "SIG_F", "T_F", "LAT_F",
    # injector geom
    "DJO", "DJF", "NO", "NF", "ANG_O", "ANG_F",
    # discharge O (16)
    "DO_CDINF", "DO_ARE", "DO_CDMIN", "DO_GEOM", "DO_DREF", "DO_DMIN", "DO_EXPS",
    "DO_LOGG", "DO_CDMAX", "DO_CDFLOOR", "DO_UPC", "DO_PREF", "DO_AP", "DO_UTC", "DO_TREF", "DO_AT",
    # discharge F (16)
    "DF_CDINF", "DF_ARE", "DF_CDMIN", "DF_GEOM", "DF_DREF", "DF_DMIN", "DF_EXPS",
    "DF_LOGG", "DF_CDMAX", "DF_CDFLOOR", "DF_UPC", "DF_PREF", "DF_AP", "DF_UTC", "DF_TREF", "DF_AT",
    # feed O / F
    "FO_DIN", "FO_AH", "FO_K0", "FO_K1", "FO_PHI",
    "FF_DIN", "FF_AH", "FF_K0", "FF_K1", "FF_PHI",
    # spray
    "SP_SMDMODEL", "SP_SMDC", "SP_SMDM", "SP_SMDP", "SP_SMDSCALE", "SP_SMDWECORR",
    "SP_GASR", "SP_GAST", "SP_ANGMODEL", "SP_ANGK", "SP_ANGN", "SP_WEMIN",
    "SP_EVAPK", "SP_EVAPXLIM", "SP_EVAPUSE",
    # solver
    "SV_CLMAX", "SV_CLCDRED", "SV_PCMIN", "SV_PCMAX", "SV_TOL", "SV_MAXIT",
    # geom
    "G_EPS", "G_AT", "G_AE", "G_VOL", "G_LSTAR", "G_DCHAM", "G_NOZZEFF",
    # combustion
    "C_MODEL", "C_C", "C_TAUREF", "C_TAUREFP", "C_TAUREFT", "C_NPRESS", "C_TSTARCAP",
    "C_HASFLOOR", "C_TAUFLOOR", "C_EMPEAK", "C_SIGMA", "C_ROPT",
    # chamber lengths (ablative wetted area only)
    "G_LEN", "G_LCYL", "G_LCONTR",
    # cooling gates + hot-gas block (ed_cooling.c)
    "K_ABLEN", "K_FILMEN", "K_REGENEN", "K_USECOUP", "K_EFFFLOOR",
    "K_HGMU", "K_HGK", "K_HGPR", "K_TI", "K_RECOV", "K_EMISHOT", "K_VIEWF", "K_DREGEN",
    # ablative material / blowing / turbulence / radiative sink
    "AB_COV", "AB_TSURF", "AB_TPYRO", "AB_HABL", "AB_CP", "AB_USEPHYS",
    "AB_BLOWEFF", "AB_BLOWC", "AB_BLOWMIN",
    "AB_TIREF", "AB_TISENS", "AB_TIEXP", "AB_TIMAX",
    "AB_EMIS", "AB_TAMB", "AB_SINKMIN", "AB_SINKFB",
    # injector-type discriminator (0=pintle, 1=impinging) -- kernels branch on it
    "INJ_TYPE",
    # pintle injector (zero for impinging configs)
    "PIN_AO", "PIN_AF", "PIN_DHO", "PIN_DHF", "PIN_DORIF", "PIN_HGAP",
    "PIN_SMDC", "PIN_SMDB", "PIN_SMDN", "PIN_SMDP", "PIN_DTIP",
    # spray turbulence corrections (used by the pintle path)
    "SP_USETURB", "SP_PENGAIN",
    # --- spray-length / evaporation block -------------------------------------------------
    # Orifice SPACING was extracted into the namespace but never made it into this vector, so
    # the kernel could not compute the doublet ring offset and therefore could not compute
    # L_imp, the spray length, or an effective residence time. Everything downstream of the
    # impingement point was invisible to the accelerated path -- which is what Layer 1 runs on.
    # Appended at the END: every pre-existing index is unchanged.
    "SPO", "SPF",
    "RHO_O_BOIL", "RHO_F_BOIL",      # boiling points, for the Spalding transfer number
    "LAT_O",                         # oxidiser latent heat (LAT_F already present)
    "EV_MODEL", "EV_CEVAP", "EV_CPGAS", "EV_APPLY_TAURES",
    # feed-line exit dump (K_exit on the d_exit bore; feed_loss.delta_p_feed)
    "FO_KX", "FO_DEX", "FF_KX", "FF_DEX",
    # NACA TN 4222 property transfer on/off (spray.smd.smd_property_scaling)
    "SP_SMDPROP",
    # Lichtarowicz (1965) Re law (discharge.cd_from_re): L/d (0 => legacy a_Re form), the
    # counterbore approach beta (0 => plenum-fed), and the orifice's pre-approach Cd_u.
    "DO_LOD", "DO_BETA", "DO_CDU", "DF_LOD", "DF_BETA", "DF_CDU",
    # Nurick cavitation limit: vapour pressure (NaN => none) and contraction coefficient
    "VP_O", "VP_F", "CC_O", "CC_F",
    # back-channel ring manifold per stream (impinging._RingManifold; NET_x = 0 => plenum)
    "NET_O", "NET_O_PORTS", "NET_O_H", "NET_O_ACH", "NET_O_DH", "NET_O_S", "NET_O_EPS",
    "NET_O_SCALE", "NET_O_AHOLE", "NET_O_DHOLE", "NET_O_KENT", "NET_O_CR",
    "NET_F", "NET_F_PORTS", "NET_F_H", "NET_F_ACH", "NET_F_DH", "NET_F_S", "NET_F_EPS",
    "NET_F_SCALE", "NET_F_AHOLE", "NET_F_DHOLE", "NET_F_KENT", "NET_F_CR",
    # measured D32 [m] (0 => the TN 4222 correlation)
    "D32M_O", "D32M_F",
]
_IDX = {n: i for i, n in enumerate(_NAMES)}
globals().update(_IDX)                      # module-level int constants for njit
NP = len(_NAMES)
 
 
def _assert_supported(st):
    """Guard the assumptions that let this port skip cooling / use the impinging path."""
    assert int(st.injector.type) in (0, 1), "injector type not ported (coaxial)"
    # Ablative IS ported (see _cooling_evaluate). Film/regen are not -- C refuses
    # them too (ed_cooling.c:147), so they stay a Python fallback.
    assert int(getattr(st.cooling, "film_enabled")) == 0 and int(getattr(st.cooling, "regen_enabled")) == 0
    # No graphite gate, deliberately: C does not check it either (ed_cooling.c
    # refuses only film/regen at :147), because graphite never enters the chamber
    # residual -- it lives in the burn/recession path (runner.py), and
    # chamber_solver.py references it zero times. Gating on it here would reject
    # configs/canonical/impinging.yaml, which C handles fine.
 
 
def extract_params(config):
    """Flatten the config scalars this port needs into a float64 vec.
 
    Delegates the field mapping to _params_from_state so there is ONE table of
    field names; the two used to carry independent copies of the whole mapping,
    which would drift the moment a field was added on one side only.
    """
    st = build_state(config)          # pure Python -- no C library required
    _assert_supported(st)
    return _params_from_state(st)
 
 
 
# ---------------------------------------------------------------------------
# state -> param vector
#
# The (index, attribute-path) mapping is STATIC, so it is built once at import
# and frozen into attrgetters. It used to be walked per call with str.split(".")
# and f-string key lookups, which cost 96 us per extraction -- 6x the cost of
# building the state itself, and paid on EVERY residual iteration of the fallback
# path via accel.solve. Same field list, same order; only the lookup is hoisted.
# ---------------------------------------------------------------------------
def _build_path_table():
    paths = {
        "RHO_O": "fluid_O.density", "MU_O": "fluid_O.viscosity",
        "SIG_O": "fluid_O.surface_tension", "T_O": "fluid_O.temperature",
        "RHO_F": "fluid_F.density", "MU_F": "fluid_F.viscosity",
        "SIG_F": "fluid_F.surface_tension", "T_F": "fluid_F.temperature",
        "LAT_F": "fluid_F.latent_heat",
        "VP_O": "fluid_O.vapor_pressure", "VP_F": "fluid_F.vapor_pressure",
        "CC_O": "cav.cc_O", "CC_F": "cav.cc_F",
        "LAT_O": "fluid_O.latent_heat",
        "RHO_O_BOIL": "fluid_O.boiling_point",
        "RHO_F_BOIL": "fluid_F.boiling_point",
        "SPO": "injector.imp_O.spacing", "SPF": "injector.imp_F.spacing",
        "EV_MODEL": "spray.evap_model_code",
        "EV_CEVAP": "spray.evap_C_evap",
        "EV_CPGAS": "spray.evap_cp_gas",
        "EV_APPLY_TAURES": "spray.evap_apply_tau_res",
        "DJO": "injector.imp_O.d_jet", "DJF": "injector.imp_F.d_jet",
        "NO": "injector.imp_O.n_elements", "NF": "injector.imp_F.n_elements",
        "ANG_O": "injector.imp_O.impingement_angle",
        "ANG_F": "injector.imp_F.impingement_angle",
    }
    for pre, side in (("DO", "discharge_O"), ("DF", "discharge_F")):
        for suf, fld in (("CDINF","Cd_inf"),("ARE","a_Re"),("CDMIN","Cd_min"),("GEOM","use_geometry_cd"),
                         ("DREF","d_ref_m"),("DMIN","d_min_m"),("EXPS","cd_small_hole_exponent"),
                         ("LOGG","cd_large_hole_log_gain"),("CDMAX","cd_inf_max"),("CDFLOOR","cd_inf_min_geom"),
                         ("UPC","use_pressure_correction"),("PREF","P_ref"),("AP","a_P"),
                         ("UTC","use_temperature_correction"),("TREF","T_ref"),("AT","a_T"),
                         ("LOD","lich_l_over_d"),("BETA","lich_beta"),("CDU","lich_cd_u")):
            paths[f"{pre}_{suf}"] = f"{side}.{fld}"
    for pre, side in (("FO", "feed_O"), ("FF", "feed_F")):
        for suf, fld in (("DIN","d_inlet"),("AH","A_hydraulic"),("K0","K0"),("K1","K1"),("PHI","phi_type"),
                         ("KX","K_exit"),("DEX","d_exit")):
            paths[f"{pre}_{suf}"] = f"{side}.{fld}"
    for suf, fld in (("SMDMODEL","smd_model"),("SMDC","smd_C"),("SMDM","smd_m"),("SMDP","smd_p"),
                     ("SMDSCALE","smd_scale"),("SMDWECORR","smd_we_corr_max"),("GASR","chamber_gas_R"),
                     ("GAST","chamber_gas_T"),("ANGMODEL","spray_angle_model"),("ANGK","spray_angle_k"),
                     ("ANGN","spray_angle_n"),("WEMIN","we_min"),("EVAPK","evap_K"),
                     ("EVAPXLIM","evap_x_star_limit"),("EVAPUSE","evap_use_constraint")):
        paths[f"SP_{suf}"] = f"spray.{fld}"
    for suf, fld in (("CLMAX","closure_max_iterations"),("CLCDRED","closure_Cd_reduction_factor"),
                     ("PCMIN","Pc_min_bound"),("PCMAX","Pc_max_bound"),("TOL","tolerance"),
                     ("MAXIT","max_iterations")):
        paths[f"SV_{suf}"] = f"solver.{fld}"
    for suf, fld in (("EPS","expansion_ratio"),("AT","A_throat"),("AE","A_exit"),("VOL","volume"),
                     ("LSTAR","Lstar"),("DCHAM","chamber_diameter"),("NOZZEFF","nozzle_efficiency"),
                     ("LEN","length"),("LCYL","length_cylindrical"),("LCONTR","length_contraction")):
        paths[f"G_{suf}"] = f"geom.{fld}"
    for suf, fld in (("MODEL","model"),("C","C"),("TAUREF","tau_ref"),("TAUREFP","tau_ref_P"),
                     ("TAUREFT","tau_ref_T"),("NPRESS","n_pressure"),("TSTARCAP","T_star_fuel_cap_K"),
                     ("HASFLOOR","has_tau_Tc_floor"),("TAUFLOOR","tau_Tc_floor"),("EMPEAK","Em_peak"),
                     ("SIGMA","mixing_sigma"),("ROPT","R_opt")):
        paths[f"C_{suf}"] = f"comb.{fld}"
    for name, fld in (("K_ABLEN","ablative_enabled"),("K_FILMEN","film_enabled"),
                      ("K_REGENEN","regen_enabled"),("K_USECOUP","use_cooling_coupling"),
                      ("K_EFFFLOOR","cooling_efficiency_floor"),("K_HGMU","hot_gas_viscosity"),
                      ("K_HGK","hot_gas_thermal_conductivity"),("K_HGPR","hot_gas_prandtl"),
                      ("K_TI","gas_turbulence_intensity"),("K_RECOV","recovery_factor"),
                      ("K_EMISHOT","radiation_emissivity_hot"),("K_VIEWF","radiation_view_factor"),
                      ("K_DREGEN","regen_chamber_inner_diameter"),
                      ("AB_COV","ablative_coverage_fraction"),
                      ("AB_TSURF","ablative_surface_temperature_limit"),
                      ("AB_TPYRO","ablative_pyrolysis_temperature"),
                      ("AB_HABL","ablative_heat_of_ablation"),("AB_CP","ablative_specific_heat"),
                      ("AB_USEPHYS","ablative_use_physics_based_blowing"),
                      ("AB_BLOWEFF","ablative_blowing_efficiency"),
                      ("AB_BLOWC","ablative_blowing_coefficient"),
                      ("AB_BLOWMIN","ablative_blowing_min_reduction_factor"),
                      ("AB_TIREF","ablative_turbulence_reference_intensity"),
                      ("AB_TISENS","ablative_turbulence_sensitivity"),
                      ("AB_TIEXP","ablative_turbulence_exponent"),
                      ("AB_TIMAX","ablative_turbulence_max_multiplier"),
                      ("AB_EMIS","ablative_surface_emissivity"),
                      ("AB_TAMB","ablative_ambient_temperature"),
                      ("AB_SINKMIN","ablative_radiative_sink_minimum_threshold"),
                      ("AB_SINKFB","ablative_radiative_sink_fallback_temperature")):
        paths[name] = f"cooling.{fld}"
    paths["INJ_TYPE"] = "injector.type"
    for suf, fld in (("AO","A_O"),("AF","A_F"),("DHO","d_hyd_O"),("DHF","d_hyd_F"),
                     ("DORIF","d_orifice"),("HGAP","h_gap"),
                     ("DTIP","d_pintle_tip")):
        paths[f"PIN_{suf}"] = f"pin.{fld}"
    for name, fld in (("PIN_SMDC","pintle_C"),("PIN_SMDB","pintle_B"),
                      ("PIN_SMDN","pintle_n"),("PIN_SMDP","pintle_p"),
                      ("SP_USETURB","use_turbulence_corrections"),
                      ("SP_PENGAIN","turbulence_penetration_gain"),
                      ("SP_SMDPROP","smd_property_scaling")):
        paths[name] = f"spray.{fld}"
    for pre, side in (("NET_O", "net_O"), ("NET_F", "net_F")):
        paths[pre] = f"{side}.enabled"
        for suf, fld in (("PORTS", "n_ports"), ("H", "h"), ("ACH", "A_ch"), ("DH", "D_h"),
                         ("S", "s"), ("EPS", "eps"), ("SCALE", "scale"), ("AHOLE", "A_hole"),
                         ("DHOLE", "d_hole"), ("KENT", "K_ent"), ("CR", "C_R")):
            paths[f"{pre}_{suf}"] = f"{side}.{fld}"
    paths["D32M_O"] = "spray.d32_measured_O"
    paths["D32M_F"] = "spray.d32_measured_F"
    missing = set(_NAMES) - set(paths)
    assert not missing, f"param(s) with no source path: {sorted(missing)}"
    return paths
 
 
_PATHS = _build_path_table()
_GETTERS = tuple((_IDX[n], _attrgetter(_PATHS[n])) for n in _NAMES)
 
 
def _params_from_state(st):
    """Flatten a state namespace (or EdEngineState) into the float64 param vector."""
    P = np.zeros(NP)
    for i, get in _GETTERS:
        P[i] = get(st)
    return P