Development Log

2026-03-28 — Pre-launch audit: 23 issues fixed (5C / 7H / 7M / 4L)

Complete pre-launch audit across scientific correctness, code quality, testing, data integrity, and production readiness. All identified issues resolved.

Critical fixes:

  • C1 Gnielinski off-by-one: if re <= 3000 → if re < 3000 — Re=3000 previously passed applicability but crashed the evaluator.

  • C2 Churchill-Bernstein lower bound: Added explicit YAML assumption surfacing that this formula is a lower bound per the original paper (CB 1977, p. 304).

  • C3 Re gap 2300–3000 diagnostics: API router now returns excluded-correlation list instead of a generic “no methods” string when no correlations are applicable.

  • C4 Petukhov uncertainty corrected: literature_uncertainty_pct raised 6% → 10% (primary source states ±10% for full Pr 0.5–2000 range).

  • C5 Film temperature advisory: Pipeline now emits warnings list when external geometry is used without wall_temperature provided.

High fixes:

  • H1/H3 Table upper-bound crashes: Hilpert Re=400,000 and Žukauskas Re=1,000,000 previously fell through all table bands and raised ValueError. Fixed by using <= on table upper bounds.

  • H2 Negative Nu guard: Turbulent plate now raises ValueError for Re < 5×10⁵ instead of returning negative Nu.

  • H4 Score clamping: RankingEngine._score() now clamps result to [0.0, 1.0].

  • H5 Dead code removed: Three unused engine singletons removed from api/dependencies.py.

  • H6 Petukhov test: Added TestPetukhov with formula accuracy and comparison tests.

  • H7 ld_min validation: Applicability engine now enforces ld_min from YAML validity dicts (using existing entry_length_ratio computed field).

Medium/Low fixes:

  • M2: _require_re_pr extracted to src/htcie/domains/_helpers.py; all three domain modules import from shared location.

  • M3: Score-range test extended to Re=1e9 (extreme extrapolation path).

  • M4: Report timestamp uses datetime.now(timezone.utc) (was naive local time).

  • M6: wall_prandtl_note metadata key added when wall-Prandtl correction is applied.

  • L4: Gnielinski test updated to reflect inclusive Re=3000 boundary.

2026-03-28 — Primary-source traceability audit (all 13 correlations)

Systematic audit of every literature_uncertainty_pct and key validity range against primary sources and authoritative textbooks. Four substantive corrections; all 13 correlations now carry explicit source-traceability notes.

Substantive corrections:

  1. Žukauskas tube bank re_min (10 → 20): Primary source p.147 (Advances in Heat Transfer Vol. 8, 1972) explicitly states the validated-data summary covers “Re from 20 to 2×10^6”. YAML had re_min: 10; Incropera references.yaml noted 16; primary source is authoritative at 20. Three-source discrepancy documented in YAML notes.

  2. Petukhov accuracy range (split by Pr): Primary source p.523 Eq.(50) states ±5–6% for Re 10^4–5×10^6 and Pr 0.5–200 separately from ±10% for Pr 0.5–2000. YAML note previously claimed ±6% uniformly for Pr up to 2000 — incorrect. Fixed with exact page citation.

  3. Churchill-Bernstein lower-bound characterization: Original paper (p.304) explicitly states Eq.(9) “is proposed as a lower bound…data generally fall somewhat above.” No ±% is stated anywhere in the paper. YAML previously said “±20% reported in original paper” — corrected to lower-bound characterization with page citation.

  4. Gnielinski ±10% attribution: The ±10% comes from Cengel & Ghajar 5th ed. (Section 8-5), not the 1976 original paper (inaccessible) or the available 2013 update (IJHMT 63:134-140, which does not restate this value). Attribution corrected.

Systematic UNCERTAIN flagging: All 13 literature_uncertainty_pct values annotated. Only Petukhov’s ±5–6%/±10% is directly confirmed from a primary source. All others are textbook-consensus estimates; each carries an explicit UNCERTAIN note explaining why the primary source could not confirm the stated bound (paywall, no ±% in paper, analytical solution only, or no single original paper).

Sources inspected: Žukauskas (1972), “Heat Transfer from Tubes in Crossflow,” Advances in Heat Transfer, Vol. 8 (pp. 142–157); Gnielinski (2013), “On heat transfer in tubes,” Int. J. Heat Mass Transfer, 63:134–140; Churchill & Bernstein (1977), “A Correlating Equation for Forced Convection from Gases and Liquids to a Circular Cylinder in Crossflow,” J. Heat Transfer (ASME), 99(2):300–306; Petukhov (1970), “Heat Transfer and Friction in Turbulent Pipe Flow with Variable Physical Properties,” Advances in Heat Transfer, Vol. 6, pp. 503–564 (p. 523); Sieder & Tate (1936), “Heat Transfer and Pressure Drop of Liquids in Tubes,” Ind. Eng. Chem., 28(12):1429–1435 (Table II).

2026-03-27 — Explicit tube bank arrangement field

Added arrangement: Optional[Literal["inline", "staggered"]] to Geometry in state.py, required when geometry_type="tube_bank". Previously the arrangement was inferred from S_T/S_L < 1.0, which made the Incropera Table 7.5 staggered S_T/S_L ≥ 2 case (C₁=0.40) permanently unreachable.

Changes: state.py (new field + validator), tube_banks.py (removed _arrangement() helper, added _require_arrangement() reading from state), YAML required_inputs for both tube bank correlations, 3 test files updated.

2026-03-27 — Validation-grade correlation audit (Incropera 7th ed.)

Verified all 13 correlations against Incropera 7th edition (primary reference) and original papers. Corrected four substantive errors:

  1. Žukauskas cylinder Pr exponent (external.zukauskas_cylinder): Fixed from hardcoded n=0.36 to n=0.37 for Pr ≤ 10, n=0.36 for Pr > 10 per Incropera Eq 7.53. This matters for gases (Pr ≈ 0.7), where the previous value was wrong.

  2. Žukauskas tube bank coefficients (tube_banks.zukauskas): Corrected all Re bands against Incropera Table 7.5:

    • Re < 100: inline 0.9→0.80, staggered 1.04→0.90

    • Re 100–1000: raised ValueError (Incropera says approximate as single cylinder; previous values 0.52/0.71 were unsourced)

    • Re > 2×10^5: inline 0.033/0.8→0.021/0.84, staggered 0.031·…/0.8→0.022/0.84

    • Added staggered S_T/S_L ≥ 2 case (C=0.40) — currently dead code pending explicit arrangement field in state schema (see TODO in tube_banks.py)

  3. Dittus-Boelter Pr lower bound: corrected pr_min from 0.7 to 0.6 per Incropera Eq 8.60. The re_max=120000 bound is retained (McAdams 1954).

  4. Sieder-Tate Pr upper bound: corrected pr_max from 17000 to 16700 per Incropera Eq 8.61.

All other correlations (Churchill-Bernstein, Hilpert, Pohlhausen, turbulent plate, Gnielinski, Petukhov, Shah laminar, Churchill-Ozoe, Grimison) verified correct.

Updated 4 YAML files, 2 domain source files, 2 test files. 167 tests pass.

2026-03-26 — HTML report renderer

  • Added src/htcie/reports/renderer.py with render_html / save_html public API.

  • Added src/htcie/reports/templates/report.html.j2 — self-contained Jinja2 template covering all report sections (input conditions, dimensionless groups, evaluations, ranking, spread, explanation).

  • Exposed render_html, save_html, dump_html_report from htcie.reports package.

  • Added “Save as HTML” button to htcie-gui evaluate page (disabled until evaluation runs).

  • Added demonstration cell to notebooks/examples.ipynb under “Using the Report Downstream”.

  • Extracted shared test fixtures to tests/unit/conftest.py; added 7 renderer tests.

2026-03-25 — Code quality and docstring pass

  • Added class and method docstrings throughout src/htcie/.

  • All formula-containing docstrings use LaTeX (:math: RST role).

  • Updated docs/architecture/overview.md with full pipeline diagram and layer-by-layer detail.

  • Updated docs/architecture/scoring.rst with correct v1 factor names, weights table, and threshold reference.

  • Updated docs/methods/metadata-schema.md to reflect all implemented fields (removed stale “planned” notes).

  • Updated correlation docs (internal.rst, external.rst, tube_banks.rst) with formula descriptions and implementation notes.

Initial scaffold

  • Renamed starter kit to htcie and regenerated the full repository scaffold.

  • Implemented seven-layer pipeline: state → registry → applicability → evaluation → ranking → confidence → explanation/report.

  • Implemented 13 correlations across three domain families: 6 internal convection, 5 external convection, 2 tube banks.

  • Implemented Scoring v1 with eight weighted factors.

  • Added FastAPI REST API, Typer CLI, and NiceGUI web interface.

  • Added JSON and Markdown report serializers.