code_constants.py

Go to the documentation of this file.

"""Physics constants and hardcoded design assumptions that live in code, not in a config field.
 
The UI's Parameters workspace ("In code" section, ``GET /api/config/parameters`` ->
``backend/routers/config.py``) reads ``CODE_CONSTANTS`` so every number that shapes a result but
has no ``Param``/schema-field provenance is at least visible, per CLAUDE.md's "every number
describing hardware carries a provenance" rule -- this module is the register for the numbers that
don't yet.
 
Each entry is a physics constant, a named lookup table, or a hardcoded threshold read straight out
of the current source (not a schema field's Python default, and not a config-editable
``design_requirements``/``Setup`` value, even one with no dedicated UI field -- those already have a
YAML path and are excluded here to avoid duplicating the Configuration tab). ``where`` is
``path/module.py:function_or_symbol`` (never a line number: lines move). ``affects_results`` is
True when the constant is on the live default path for at least one shipped injector/propellant
combination; False when it only feeds a diagnostic, a report-only model, or a legacy/inactive path.
 
Scope (2026-09-26, after the overnight physics pass in wave1_layer1/combustion/injector/
thermal_chamber.md and report_wave2a.json): engine/core, engine/pipeline,
engine/optimizer/layers/layer1_static_optimization.py, engine/core/injectors/layout.py,
ui/flight_sim.py. Excludes unit conversions (PSI, IN, RANKINE_PER_KELVIN, ...), array/grid sizes and
solver iteration counts/tolerances (MACH_SOLVER_MAX_ITERATIONS, PC_BRACKET_SCAN_POINTS, ...).
 
See also: docs/hidden-physical-parameters.md (parameters with a config path but no form field --
a different, overlapping list) and tests/test_code_constants.py (schema + existence check).
"""
 
from __future__ import annotations
 
from typing import Any, Dict, List
 
CODE_CONSTANTS: List[Dict[str, Any]] = [
    # ------------------------------------------------------------------ Propellants ---
    {
        "name": "_FLUID_THERMO_FALLBACKS",
        "value": "{lox:(1140,213000,90.2,154.6), methane:(422.6,510000,111.7,190.6), ethanol:(789,838000,351.4,514.0), rp1:(810,246000,489.0,678.0), ipa:(786,665500,355.6,508.3), n2o:(1220,376000,184.7,309.5), h2:(70.8,446000,20.3,33.15), n2:(806,199000,77.36,126.2)}",
        "where": "engine/pipeline/stability/analysis.py:_FLUID_THERMO_FALLBACKS",
        "meaning": "Density/L_vap/Tboil/Tcrit per propellant, used when CoolProp has no state for the stability model.",
        "category": "Propellants",
        "affects_results": True,
    },
    {
        "name": "_GENERIC_THERMO",
        "value": "{fuel:(800,300000,450,600), oxidizer:(1140,213000,90.2,154.6)}",
        "where": "engine/pipeline/stability/analysis.py:_GENERIC_THERMO",
        "meaning": "Generic fuel/oxidizer thermo fallback when the propellant name matches no table row.",
        "category": "Propellants",
        "affects_results": False,
    },
    {
        "name": "DEFAULT_LOX_DENS_KG_M3",
        "value": "1140.0",
        "where": "engine/pipeline/constants.py:DEFAULT_LOX_DENS_KG_M3",
        "meaning": "Fallback LOX density when a fluid object has none; feeds default Cd/Re fallback paths.",
        "category": "Propellants",
        "affects_results": False,
    },
    {
        "name": "DEFAULT_FUEL_DENS_KG_M3 / DEFAULT_FUEL_BOILING_POINT_K",
        "value": "810.0 kg/m3 / 489.0 K",
        "where": "engine/pipeline/constants.py:DEFAULT_FUEL_DENS_KG_M3",
        "meaning": "RP-1-like fallback fuel density and boiling point when a fluid object is incomplete.",
        "category": "Propellants",
        "affects_results": False,
    },
    # ------------------------------------------------------------------ Injector ---
    {
        "name": "IMPINGEMENT_LD_TARGET_DEFAULT",
        "value": "4.0",
        "where": "engine/core/injectors/layout.py:IMPINGEMENT_LD_TARGET_DEFAULT",
        "meaning": "Target axial standoff L/d (impingement height over mean jet diameter) Layer 1 aims for.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "IMPINGEMENT_LD_TOL_UNDERIVED",
        "value": "1.0",
        "where": "engine/core/injectors/layout.py:IMPINGEMENT_LD_TOL_UNDERIVED",
        "meaning": "Half-width of the standoff L/d search band when spacing is not derived and no band is given.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "_COS_FLOOR",
        "value": "0.10",
        "where": "engine/core/injectors/layout.py:_COS_FLOOR",
        "meaning": "Floor on |cos(theta)| sizing an inclined hole's footprint, so a near-90 deg jet is finite.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "DRILL_LD_PRACTICE_MAX",
        "value": "10.0",
        "where": "engine/core/injectors/layout.py:DRILL_LD_PRACTICE_MAX",
        "meaning": "Twist-drill practice limit (L/d); past this a shop reaches for gundrill/EDM (warning only).",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "ORIFICE_LD_MIN",
        "value": "4.0",
        "where": "engine/core/injectors/layout.py:ORIFICE_LD_MIN",
        "meaning": "SP-8089 3.1.2.2 minimum hole L/d for a jet that leaves concentric with the hole (warning).",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "DRILL_ENTRY_MAX_OFF_SQUARE_DEG",
        "value": "10.0",
        "where": "engine/core/injectors/layout.py:DRILL_ENTRY_MAX_OFF_SQUARE_DEG",
        "meaning": "Solid-carbide drill's max off-square entry angle before a flat must be milled first (warning).",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "FACE_HEATING_INCLUDED_DEG",
        "value": "90.0",
        "where": "engine/core/injectors/layout.py:FACE_HEATING_INCLUDED_DEG",
        "meaning": "SP-8089 p.26: included angle above which the injector face sees high heat flux (warning).",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "FREE_JET_MAX_D",
        "value": "7.0",
        "where": "engine/core/injectors/layout.py:FREE_JET_MAX_D",
        "meaning": "SP-8089 3.1.1.1.4: max impingement distance along the jet, in orifice diameters; hard gate.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "CORE_FRAC_WARN",
        "value": "0.25",
        "where": "engine/core/injectors/layout.py:CORE_FRAC_WARN",
        "meaning": "Chamber cross-section fraction inside the impingement circle below which spray feeds a core.",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "EXIT_LAND_DEFAULT",
        "value": "0.0005",
        "where": "engine/core/injectors/layout.py:EXIT_LAND_DEFAULT",
        "meaning": "Assumed metal left around a drilled exit on a contoured face when plate.exit_land is unset [m].",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "PLATE_THICKNESS_DEFAULT",
        "value": "0.0127",
        "where": "engine/core/injectors/layout.py:PLATE_THICKNESS_DEFAULT",
        "meaning": "Assumed injector plate thickness (0.5 in) when layer1_injector_plate_thickness_m is unset.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "MANIFOLD_Q_FRAC",
        "value": "0.05",
        "where": "engine/core/injectors/layout.py:MANIFOLD_Q_FRAC",
        "meaning": "Channel velocity head allowed as a fraction of injector dp; above it the layout flags 'bad'.",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "PLATE_YIELD_FACTOR",
        "value": "1.5",
        "where": "engine/core/injectors/layout.py:PLATE_YIELD_FACTOR",
        "meaning": "Factor on declared plate yield strength the injector plate-bending check allows (assumed).",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "PLATE_POISSON_DEFAULT",
        "value": "0.3",
        "where": "engine/core/injectors/layout.py:PLATE_POISSON_DEFAULT",
        "meaning": "Plate Poisson ratio for the plate-bending check when injector.plate.poisson_ratio is unset.",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "layout consistency check: plate vs. Cd L/d mismatch",
        "value": "0.25",
        "where": "engine/core/injectors/layout.py:layout_from_config",
        "meaning": "L/d difference between the drawn plate and the Cd model's L/d that triggers a mismatch warning.",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "igniter clearance check: center-clear vs. keepout ratio",
        "value": "1.2",
        "where": "engine/core/injectors/layout.py:layout_from_config",
        "meaning": "A declared center-clear diameter over 1.2x the igniter's keepout diameter raises an error.",
        "category": "Injector",
        "affects_results": False,
    },
    {
        "name": "INJECTOR_DISCHARGE_BASELINES",
        "value": "{pintle: Cd_inf O=0.40 F=0.65 (fixed); impinging: Cd_inf O=F=0.60 (geometry-scaled)}",
        "where": "engine/core/dispatch.py:INJECTOR_DISCHARGE_BASELINES",
        "meaning": "Discharge-Cd values stamped onto discharge.{oxidizer,fuel} whenever the UI switches injector type.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "_GEOMETRY_CD_PARAMS['cd_small_hole_exponent']",
        "value": "0.20",
        "where": "engine/core/dispatch.py:_GEOMETRY_CD_PARAMS",
        "meaning": "Small-hole Cd exponent re-stamped on every switch to impinging; contradicts the 0.0 config default.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "INJECTOR_GEOMETRY_TEMPLATES",
        "value": "pintle: 14 LOX orifices d=2.72mm; impinging: 20+20 elements d=2mm, 50/60 deg",
        "where": "engine/core/dispatch.py:INJECTOR_GEOMETRY_TEMPLATES",
        "meaning": "Starting injector.geometry block stamped in whenever the UI switches injector type.",
        "category": "Injector",
        "affects_results": True,
    },
    {
        "name": "turbulence intensity correlation (pipe flow, Re^-0.125)",
        "value": "0.16 * Re^-0.125, clipped [0.02, 0.3] per stream / [0.02, 0.35] mixed; length scale 0.07*d_hyd",
        "where": "engine/core/injectors/impinging.py:ImpingingInjector.solve",
        "meaning": "Fully-developed pipe turbulence intensity estimate; feeds pintle spray penetration, else diagnostic-only.",
        "category": "Injector",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Discharge & Cd ---
    {
        "name": "INLET_GEOMETRY_CD",
        "value": "{sharp:0.80, chamfered:0.84, conical:0.86, rounded_light:0.85, rounded:0.88, bellmouth:0.95}",
        "where": "engine/core/discharge.py:INLET_GEOMETRY_CD",
        "meaning": "Short-tube (L/d 2-5) Cd by named inlet treatment, Huzel & Huang practitioner table.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "INLET_GEOMETRY_RD",
        "value": "{sharp:0.0, chamfered:0.03, conical:0.04, rounded_light:0.05, rounded:0.125, bellmouth:0.20}",
        "where": "engine/core/discharge.py:INLET_GEOMETRY_RD",
        "meaning": "Inlet rounding r/d nominally achieved by each named inlet treatment, for the continuous Cd model.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "cd_from_inlet_radius_ratio fit constants",
        "value": "cd_sharp=0.80, cd_max=0.96, k=7.622",
        "where": "engine/core/discharge.py:cd_from_inlet_radius_ratio",
        "meaning": "Saturating-exponential fit of short-tube Cd vs inlet rounding r/d through 3 practitioner anchors.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "LICHTAROWICZ_A / LICHTAROWICZ_B",
        "value": "0.827 / 0.0085",
        "where": "engine/core/discharge.py:LICHTAROWICZ_A",
        "meaning": "Lichtarowicz (1965) sharp-inlet long-orifice Cd_u = A - B*(L/d), valid L/d 2-10.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "LICHTAROWICZ_LD_MAX",
        "value": "10.0",
        "where": "engine/core/discharge.py:LICHTAROWICZ_LD_MAX",
        "meaning": "Longest L/d covered by the Lichtarowicz data; past this the fit's slope is extrapolated.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "COUNTERBORE_ENTRANCE_K",
        "value": "0.5",
        "where": "engine/core/discharge.py:COUNTERBORE_ENTRANCE_K",
        "meaning": "Idelchik sharp-inlet loss coefficient for a plenum-to-counterbore entrance (plenum-back plates).",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    {
        "name": "cd_length_factor 'piecewise' thin-plate blend",
        "value": "0.7625 + 0.11875 * (L/d) below L/d=2 (so sharp*0.7625 = 0.61 thin-plate anchor)",
        "where": "engine/core/discharge.py:cd_length_factor",
        "meaning": "Legacy (opt-in) Cd-vs-L/d curve's blend to the thin-plate value below L/d 2; unsourced.",
        "category": "Discharge & Cd",
        "affects_results": False,
    },
    {
        "name": "cd_length_factor 'piecewise' friction roll-off",
        "value": "1.0 - 0.012 * (L/d - 5), floored at 0.85, flat over L/d 2-5",
        "where": "engine/core/discharge.py:cd_length_factor",
        "meaning": "Legacy (opt-in) Cd-vs-L/d curve's decline above L/d 5 (1.2%/L/d); unsourced.",
        "category": "Discharge & Cd",
        "affects_results": False,
    },
    {
        "name": "NURICK_CC0 / NURICK_RD_GAIN",
        "value": "0.62 / 11.4",
        "where": "engine/core/discharge.py:NURICK_CC0",
        "meaning": "Nurick (1976) vena-contracta Cc0 and its inlet-rounding gain; feeds the cavitation report only.",
        "category": "Discharge & Cd",
        "affects_results": False,
    },
    {
        "name": "cd_inf_from_inlet_geometry physical cap",
        "value": "0.98",
        "where": "engine/core/discharge.py:cd_inf_from_inlet_geometry",
        "meaning": "Hard ceiling on any inlet/L-d/counterbore-combined Cd, so no orifice reports above 0.98.",
        "category": "Discharge & Cd",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Combustion efficiency ---
    {
        "name": "WATSON_EXPONENT",
        "value": "0.38",
        "where": "engine/pipeline/combustion_physics.py:WATSON_EXPONENT",
        "meaning": "Watson (1943) exponent for latent heat vs. reduced temperature, used in the drop evaporation march.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    {
        "name": "spray_vaporization_march: Ranz-Marshall Nu correlation",
        "value": "Nu = 2.0 + 0.6 * Re_f^0.5 * Pr^(1/3)",
        "where": "engine/pipeline/combustion_physics.py:spray_vaporization_march",
        "meaning": "Ranz-Marshall droplet Nusselt-number correlation driving the d^2-law evaporation rate.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    {
        "name": "spray_vaporization_march: Putnam drag correction",
        "value": "phi = 1 + Re^(2/3)/6 for Re < 1000, else 0.424*Re/24",
        "where": "engine/pipeline/combustion_physics.py:spray_vaporization_march",
        "meaning": "Putnam's drag-coefficient correction to Stokes drag on an evaporating drop, by Reynolds regime.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    {
        "name": "spray_vaporization_march: 1/3-rule film temperature",
        "value": "T_f = T_s + (T_c - T_s) / 3",
        "where": "engine/pipeline/combustion_physics.py:spray_vaporization_march",
        "meaning": "Film-property reference temperature (1/3-rule) for a drop's boundary-layer gas properties.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    {
        "name": "_V_FLOOR",
        "value": "1.0e-3 m/s",
        "where": "engine/pipeline/combustion_physics.py:_V_FLOOR",
        "meaning": "Velocity floor for a drop stalled at the injector face, so the march never divides by zero.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    {
        "name": "legacy gasification: vapor-diffusivity correlation",
        "value": "D_M_REF=5e-5 m2/s at D_M_T_REF=1500 K, D_M_P_REF=2.5e6 Pa; D ~ (T/Tref)^1.75 * (Pref/P)",
        "where": "engine/pipeline/physics_constants.py:D_M_REF",
        "meaning": "Reference vapor diffusivity and its T/P scaling for the legacy single-drop gasification helper.",
        "category": "Combustion efficiency",
        "affects_results": False,
    },
    {
        "name": "legacy gasification: U_SLIP_CAP / D_MIN_GASIFICATION",
        "value": "50.0 m/s / 1e-6 m",
        "where": "engine/pipeline/physics_constants.py:U_SLIP_CAP",
        "meaning": "Slip-velocity cap and minimum drop size for the legacy gasification helper (progress diagnostic only).",
        "category": "Combustion efficiency",
        "affects_results": False,
    },
    {
        "name": "CARBON_OXIDISERS reaction enthalpies",
        "value": "H2O:+10.93MJ/kg, CO2:+14.36MJ/kg, OH:+5.67MJ/kg, O2:-9.20MJ/kg, O:-29.95MJ/kg (per kg carbon)",
        "where": "engine/pipeline/thermal/graphite_cooling.py:CARBON_OXIDISERS",
        "meaning": "JANAF heats of reaction per kg carbon consumed, for each graphite-throat oxidiser species.",
        "category": "Combustion efficiency",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Chamber & nozzle ---
    {
        "name": "PC_CHOKE_FLOOR_PA",
        "value": "2.0 * 101325.0 Pa (2 atm)",
        "where": "engine/core/chamber_solver.py:PC_CHOKE_FLOOR_PA",
        "meaning": "Floor of the chamber-pressure search: below it the sonic-throat demand model breaks down.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "PC_MIN_TOTAL_DROP_FRAC",
        "value": "0.02",
        "where": "engine/core/chamber_solver.py:PC_MIN_TOTAL_DROP_FRAC",
        "meaning": "Minimum feed+injector pressure drop (as a fraction of tank pressure) allowed in the Pc search.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "Rao contour throat arc radii",
        "value": "upstream 1.5 * R_t, downstream 0.382 * R_t",
        "where": "engine/core/nozzle_solver.py:rao",
        "meaning": "Standard Rao parabolic-bell throat entrance/exit circular-arc radii, as multiples of throat radius.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "NOZZLE_ANGLES_TABLE",
        "value": "theta_n/theta_e by expansion ratio (4-100) and bell percent (60-100%), parabola-angle chart",
        "where": "engine/core/nozzle_angles.py:NOZZLE_ANGLES_TABLE",
        "meaning": "Rao nozzle entrance/exit half-angle lookup table used to draw the bell contour.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_BELL_FRACTION",
        "value": "0.8",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_BELL_FRACTION",
        "meaning": "Fraction of a full-length Rao bell Layer 1 draws and uses for the engine-length gate.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "_layer1_chamber_od_floor_m: minimum contraction ratio",
        "value": "1.05",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_layer1_chamber_od_floor_m",
        "meaning": "Floor on D/Dt used to size the smallest chamber OD worth searching, when dt_ratio_min is looser.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "_layer1_chamber_mass_kg: Roark fixed-edge closure-plate coefficient",
        "value": "0.75",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_layer1_chamber_mass_kg",
        "meaning": "Roark Table 11.2 fixed-edge round-plate stress coefficient sizing the injector-face closure mass term.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_DEFAULT_EXIT_PRESSURE_INSIDE_QUAD",
        "value": "0.35",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_DEFAULT_EXIT_PRESSURE_INSIDE_QUAD",
        "meaning": "Default weight on the quadratic penalty keeping the nozzle exit pressure near ambient.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    {
        "name": "_DERIVE_AT_SLOPE_DEFAULT / MIN / MAX",
        "value": "0.35 / 0.12 / 1.20",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_DERIVE_AT_SLOPE_DEFAULT",
        "meaning": "Measured dlnF/dlnAt slope (ethalox impinging) and its clamp band for deriving throat area.",
        "category": "Chamber & nozzle",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Thermal protection ---
    {
        "name": "BARTZ_OMEGA",
        "value": "0.6",
        "where": "engine/pipeline/thermal/gas_side.py:BARTZ_OMEGA",
        "meaning": "Bartz boundary-layer viscosity-temperature exponent (H&H eq. 4-14) in the property correction.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "bartz_h leading coefficient",
        "value": "0.026",
        "where": "engine/pipeline/thermal/gas_side.py:bartz_h",
        "meaning": "Leading empirical coefficient of the Bartz gas-side heat-transfer correlation (H&H eq. 4-13).",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "THROAT_RC_OVER_RT",
        "value": "0.5 * (1.5 + 0.382)",
        "where": "engine/pipeline/thermal/gas_side.py:THROAT_RC_OVER_RT",
        "meaning": "Bartz's throat radius-of-curvature term, taken as the mean of the drawn contour's two arc radii.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "LECKNER_T_MAX",
        "value": "2500.0 K",
        "where": "engine/pipeline/thermal/gas_side.py:LECKNER_T_MAX",
        "meaning": "Temperature above which Leckner's emissivity pressure correction is held fixed (fit range limit).",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "BEAM_LENGTH_COEFF / CYLINDER_BEAM_LENGTH_OVER_D",
        "value": "3.6 / 0.95",
        "where": "engine/pipeline/thermal/gas_side.py:BEAM_LENGTH_COEFF",
        "meaning": "Mean gas radiation beam length: 3.6*V/A general enclosure, capped at 0.95x local bore diameter.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "_LECKNER_H2O / _LECKNER_CO2 emissivity coefficients",
        "value": "3x3 (H2O) and 3x4 (CO2) polynomial coefficient matrices",
        "where": "engine/pipeline/thermal/gas_side.py:_LECKNER_H2O",
        "meaning": "Leckner (Modest Table 11.3) zero-pressure gas emissivity polynomial fit coefficients for H2O/CO2.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "gas_absorptivity: Hottel scaling exponents",
        "value": "n_H2O=0.45, n_CO2=0.65",
        "where": "engine/pipeline/thermal/gas_side.py:gas_absorptivity",
        "meaning": "Hottel's temperature-scaling exponents converting gas emissivity to wall-emission absorptivity.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "R_GAS / MW_C",
        "value": "8.314462618 J/(mol K) / 12.0107 kg/kmol",
        "where": "engine/pipeline/thermal/graphite_cooling.py:MW_C",
        "meaning": "Universal gas constant and carbon molar mass used to stoichiometrically size graphite recession.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "calculate_throat_heuristic_multiplier defaults",
        "value": "fallback 1.3, velocity exponent 0.8, pressure exponent 0.2, turbulence_enhancement 1.1, clamp [1.2, 2.5]",
        "where": "engine/pipeline/thermal/graphite_cooling.py:calculate_throat_heuristic_multiplier",
        "meaning": "Heuristic throat-vs-chamber recession multiplier still used on runner.py's legacy time-varying path.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "calculate_local_recession_rate: pyrolysis-to-gas surface temperature blend",
        "value": "T_surface = pyrolysis_temp + 0.1*(T_gas - pyrolysis_temp), capped at 0.95*T_gas",
        "where": "engine/pipeline/thermal/ablative_geometry.py:calculate_local_recession_rate",
        "meaning": "Heuristic interpolation for an ablative surface's temperature above pyrolysis, on the legacy path.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    {
        "name": "calculate_local_recession_rate defaults",
        "value": "blowing_efficiency=0.8, char_layer_conductivity=0.2 W/(m K), char_layer_thickness=0.001 m",
        "where": "engine/pipeline/thermal/ablative_geometry.py:calculate_local_recession_rate",
        "meaning": "Assumed char-layer properties for the legacy (non-liner_response) ablative recession calculation.",
        "category": "Thermal protection",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Stability ---
    {
        "name": "DEFAULT_OVERLAP",
        "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}",
        "where": "engine/pipeline/stability/acoustic.py:DEFAULT_OVERLAP",
        "meaning": "Assumed, uncalibrated mode-shape/heat-release overlap per acoustic mode driving the HF gate.",
        "category": "Stability",
        "affects_results": True,
    },
    {
        "name": "TRANSVERSE_EIGENVALUES",
        "value": "{1T:1.84118, 2T:3.05424, 1R:3.83171, 3T:4.20119, 1T1R:5.33144}",
        "where": "engine/pipeline/stability/core.py:TRANSVERSE_EIGENVALUES",
        "meaning": "Zeros of J'_m (velocity-boundary Bessel roots) setting transverse acoustic mode frequencies.",
        "category": "Stability",
        "affects_results": True,
    },
    {
        "name": "sensitive_time_lag: chi default",
        "value": "0.5",
        "where": "engine/pipeline/stability/core.py:sensitive_time_lag",
        "meaning": "Default sensitive-lag fraction chi (tau_sens = chi*tau_vap); the model's single largest uncertainty.",
        "category": "Stability",
        "affects_results": True,
    },
    {
        "name": "stability_score display mapping",
        "value": "clip((margin - 0.85) / 0.45, 0, 1)",
        "where": "engine/pipeline/stability/analysis.py:stability_score",
        "meaning": "Fixed linear map from the limiting gain-margin gate to the reported 0-1 stability score.",
        "category": "Stability",
        "affects_results": False,
    },
    {
        "name": "_TUBE_E_STAINLESS",
        "value": "193.0e9 Pa",
        "where": "engine/pipeline/stability/analysis.py:_TUBE_E_STAINLESS",
        "meaning": "Assumed 300-series stainless Young's modulus for a feed tube whose material isn't configured.",
        "category": "Feed & tanks",
        "affects_results": True,
    },
    {
        "name": "_liquid_bulk_modulus generic fallback",
        "value": "1.5e9 Pa",
        "where": "engine/pipeline/stability/analysis.py:_liquid_bulk_modulus",
        "meaning": "Generic liquid bulk modulus used for water-hammer/line-frequency when CoolProp has no state.",
        "category": "Feed & tanks",
        "affects_results": True,
    },
    {
        "name": "_drop: assumed injector/feed pressure-drop fractions",
        "value": "delta_p_injector = 0.30 * Pc; delta_p_feed = 0.10 * Pc",
        "where": "engine/pipeline/stability/analysis.py:_drop",
        "meaning": "Assumed injector and feed pressure-drop fractions of Pc when the solver reports none, for the chug gate.",
        "category": "Stability",
        "affects_results": True,
    },
    {
        "name": "_feed_geometry: assumed feed line length",
        "value": "0.305 m",
        "where": "engine/pipeline/stability/analysis.py:_feed_geometry",
        "meaning": "Assumed tank-outlet-to-manifold feed length for the chug inertance when feed_system.length is unset.",
        "category": "Feed & tanks",
        "affects_results": True,
    },
    {
        "name": "_feed_geometry: assumed feed inlet diameter",
        "value": "0.0127 m",
        "where": "engine/pipeline/stability/analysis.py:_feed_geometry",
        "meaning": "Assumed feed-line bore for the chug inertance when the feed system declares no area at all.",
        "category": "Feed & tanks",
        "affects_results": True,
    },
    {
        "name": "_chamber_dims: assumed chamber length / diameter",
        "value": "0.18 m / 0.1 m",
        "where": "engine/pipeline/stability/analysis.py:_chamber_dims",
        "meaning": "Assumed chamber length and diameter for the acoustic-mode model when no geometry has been solved.",
        "category": "Stability",
        "affects_results": True,
    },
    {
        "name": "build_stability_inputs: assumed nozzle-entrance Mach number",
        "value": "0.2",
        "where": "engine/pipeline/stability/analysis.py:build_stability_inputs",
        "meaning": "Assumed mean Mach at the nozzle entrance (sets convective/nozzle acoustic damping) if not derivable.",
        "category": "Stability",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Feed & tanks ---
    {
        "name": "FEED_LINE_D_3_8_IN_NOMINAL_M and dual-line equivalents",
        "value": "(3/8) * 25.4e-3 m nominal bore; dual-line equivalent d_inlet = d * sqrt(2)",
        "where": "engine/pipeline/constants.py:FEED_LINE_D_3_8_IN_NOMINAL_M",
        "meaning": "Reference 3/8 in tube bore and its twin-parallel-line equivalent diameter for feed_system presets.",
        "category": "Feed & tanks",
        "affects_results": True,
    },
    # ------------------------------------------------------------------ Vehicle & flight ---
    {
        "name": "GAMMA_AIR / R_AIR",
        "value": "1.4 / 287.05287 J/(kg K)",
        "where": "engine/pipeline/vehicle_drag.py:R_AIR",
        "meaning": "Air specific-heat ratio and gas constant (US Standard Atmosphere 1976) for the drag build-up.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "isa_troposphere: US Standard Atmosphere 1976 constants",
        "value": "T0=288.15K, lapse=0.0065 K/m to 11000m, then 216.65K isothermal to 20000m",
        "where": "engine/pipeline/vehicle_drag.py:isa_troposphere",
        "meaning": "Sea-level temperature, lapse rate and tropopause/stratosphere boundaries for the flight atmosphere.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "isa_troposphere: Sutherland's law constants",
        "value": "mu = 1.458e-6 * T^1.5 / (T + 110.4)",
        "where": "engine/pipeline/vehicle_drag.py:isa_troposphere",
        "meaning": "Sutherland's law coefficients for air viscosity, feeding the drag build-up's Reynolds number.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "skin_friction_cf: turbulent Cf formula",
        "value": "1.48e-2 below Re=1e4, else 1 / (1.50*ln(Re) - 5.6)^2",
        "where": "engine/pipeline/vehicle_drag.py:skin_friction_cf",
        "meaning": "Niskanen (2013) eq. 3.81 fully-turbulent flat-plate friction coefficient vs. Reynolds number.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "skin_friction_cf: compressibility correction",
        "value": "c_turb = 1 - 0.1*M^2 (M<1.1), else 1/(1+0.15*M^2)^0.58",
        "where": "engine/pipeline/vehicle_drag.py:skin_friction_cf",
        "meaning": "Niskanen eq. 3.82/3.83 compressibility correction to turbulent skin friction, subsonic/supersonic.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "base_cd",
        "value": "0.12 + 0.13*M^2 for M<=1, else 0.25/M",
        "where": "engine/pipeline/vehicle_drag.py:base_cd",
        "meaning": "Niskanen eq. 3.94 base-drag coefficient vs. Mach number for the aft end of the vehicle.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "nose_pressure_cd: stagnation coefficient",
        "value": "0.8 * sin(phi)^2",
        "where": "engine/pipeline/vehicle_drag.py:nose_pressure_cd",
        "meaning": "Niskanen eq. 3.86 subsonic nose pressure-drag coefficient from the local half-angle phi.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "_STONEY_FN3",
        "value": "von Karman / LV-Haack wave-drag Cd vs Mach (0.9-3.0), fineness-3 nose, tabulated",
        "where": "engine/pipeline/vehicle_drag.py:_STONEY_FN3",
        "meaning": "Stoney (NASA TR R-100) transonic/supersonic nose wave-drag table, as OpenRocket tabulates it.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "setup_flight: engine/propulsion inertia proxy geometry",
        "value": "engine_r=0.6*rocket_radius, engine_h=0.3 m, prop_r=0.8*rocket_radius, prop_h=0.5 m",
        "where": "ui/flight_sim.py:setup_flight",
        "meaning": "Assumed engine/propulsion-system envelope used to estimate moment of inertia when none is modeled.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "setup_flight: cm_wo_motor fallback",
        "value": "motor_position + 1.5 m",
        "where": "ui/flight_sim.py:setup_flight",
        "meaning": "Assumed rocket center-of-mass without the motor when config.rocket.cm_wo_motor is unset.",
        "category": "Vehicle & flight",
        "affects_results": True,
    },
    {
        "name": "burn_analysis: throat-growth warning threshold",
        "value": "20.0 %",
        "where": "engine/pipeline/burn_analysis.py:analyze_burn_degradation",
        "meaning": "Throat-area growth over a burn above which the burn-progression report flags a warning.",
        "category": "Vehicle & flight",
        "affects_results": False,
    },
    # ------------------------------------------------------------------ Optimizer ---
    {
        "name": "_layer1_valley_escape_tier thresholds",
        "value": "tier 3: evals>5000 & stagnation>1000; tier 2: >3000 & >500; tier 1: >1500 & >300",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_layer1_valley_escape_tier",
        "meaning": "Evaluation-count and stagnation thresholds that boost CMA-ES sigma while no feasible design exists.",
        "category": "Optimizer",
        "affects_results": True,
    },
    {
        "name": "valley escape sigma boost_factors",
        "value": "block/refresh path [1.0, 1.5, 2.0, 3.0]; legacy path [1.0, 2.0, 4.0, 8.0]",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_layer1_valley_escape_tier",
        "meaning": "CMA-ES step-size multipliers applied per valley-escape tier to jump out of an infeasible plateau.",
        "category": "Optimizer",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_DEFAULT_MIN_STABILITY_MARGIN",
        "value": "1.2",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_DEFAULT_MIN_STABILITY_MARGIN",
        "meaning": "Default chug gain-margin requirement Layer 1 signs off against when none is configured.",
        "category": "Optimizer",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_DEFAULT_INFEASIBILITY_GATE_EPS",
        "value": "0.002",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_DEFAULT_INFEASIBILITY_GATE_EPS",
        "meaning": "Slack added to feasibility gates so a design sitting exactly on a limit still scores feasible.",
        "category": "Optimizer",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_DEFAULT_MOMENTUM_LOG_DEADBAND_REL",
        "value": "0.0",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_DEFAULT_MOMENTUM_LOG_DEADBAND_REL",
        "meaning": "Default dead-band (relative, log space) around the momentum-ratio target before the term penalizes.",
        "category": "Optimizer",
        "affects_results": True,
    },
    {
        "name": "_LAYER1_DEFAULT_DP_O_BAND / _LAYER1_DEFAULT_DP_F_BAND",
        "value": "(0.20, 0.40)",
        "where": "engine/optimizer/layers/layer1_static_optimization.py:_LAYER1_DEFAULT_DP_O_BAND",
        "meaning": "Default injector dp/Pc band per side; a config's 0.15-0.35 is silently widened to this exact band.",
        "category": "Optimizer",
        "affects_results": True,
    },
]