Introduction#

This documentation describes the HyFlux v10 calculation engine as it is implemented in src/engine/ — every formula shown is the formula the code evaluates, and every page names its source function, its test evidence, its implementation status against the CASCADE coverage matrix, and its known deviations. Where a formulation reproduces a published CASCADE equation, the CASCADE equation label is cited (cf. [Boeing, 2026]); the surrounding prose is HyFlux’s own.

Nomenclature#

Units#

  • GtCO₂ / MtCO₂ — giga-/mega-tonnes of carbon dioxide (or CO₂-equivalent, where stated). The engine’s headline emissions are in GtCO₂; the removal module works in MtCO₂ and converts at the wedge boundary (÷1000), a unit boundary covered explicitly by the test suite.

  • TTW / WTW — tank-to-wake (combustion only) vs well-to-wake (full life-cycle) emissions. The engine is canonical at WTW; the UI display scope (scope: 'wtw' | 'ttw' | 'nonco2') is a presentation multiplier only. Reference anchors: Jet-A1 WTW 89 gCO₂e/MJ, TTW 74, WtT 15 (constants.ts).

  • EJ / MJ — exajoules and megajoules of energy (LHV basis throughout). The energy-demand roll-up works in EJ; per-flight route energy in MJ. Conversion identity: 1 GtCO₂ at 89 gCO₂e/MJ ⇔ 1000/89 ≈ 11.236 EJ (energyDemand.ts:GT_CO2_TO_EJ).

Route-level vs fleet-level symbols#

CASCADE’s introduction uses lower-case symbols for route-level quantities (\(d\), \(e\), \(n\), \(x\)) and upper-case for fleet-level aggregates (\(E\), \(G\)). HyFlux keeps the same convention where it is meaningful: the route-level Future Aircraft module (futureAircraft.ts) uses lower-case per-route quantities (\(e^*(d)\), \(n_{in}(rt,t)\), \(x(ac_{fut},rt,t)\)), aggregated to fleet totals (\(E(t)\), \(G\)). The aggregate engine (cascade.ts) has no route dimension, so its quantities are fleet-level by construction — an honest limitation recorded on each affected page (cf. CASCADE Introduction, nomenclature).

Two-track baselines#

HyFlux preserves a frozen legacy baseline alongside corrected defaults, so that historical parity evidence remains reproducible while defects are fixed in the default path. Three scenario switches control this (decision log DL-006, DL-012, DL-022, DL-024):

  • traffic_model: 'cascade_series' (default) compounds the 2019 baseline exactly like the time-series sweep; 'legacy_anchor' reproduces the frozen v3.3 scalar anchor (2.82 Gt at defaults) pinned by the parity spec.

  • offset_mode: 'constrained' (default) bounds the offsets wedge by physical removal capacity applied to residual emissions; 'percent' reproduces the legacy unconstrained gross-percentage behaviour.

  • ptl_model: 'cascade_stoich' (default) evaluates the stoichiometric PtL carbon-intensity formulation; 'legacy_factor' keeps the pre-DL-024 single-factor curve.

Rule: any change that alters a default result is explained number-by-number in a phase report; the frozen track is never silently rebased (Phase1-Regression-Report.md §1, Completion-Report-2026-07-18.md §1).

Synthetic-data disclaimer#

All traffic and aircraft reference data in HyFlux are synthetic, first-principles substitutes chosen to be plausible: the 24-route traffic dataset (Air Traffic Dataset), the 16 range-energy reference tables (Aircraft — Fleet Renewal & Future Aircraft), and the Cirium-benchmark corridor panel (src/data/cirium-mock.ts) contain no measured, licensed or proprietary values. Data is deterministic (hard-coded tables, pure functions, no RNG) and injectable — every consumer accepts an override — so licensed data can be dropped in later without touching the model. No exact value-parity claim against Boeing’s datasets is made or implied anywhere in this documentation.