Fast-JX: correct bin 17-18 tables (TOA flux, Rayleigh, O3 attenuation) to Cloud-J v8.0 — fixes J_NO2 ~2x low

[xk-y]

Summary

Fast-JX's 18-bin photolysis cross-sections are Cloud-J v8.0 (the NO2 300 K row and the NO3 190/298c rows match FJX_spec.dat digit-for-digit), but the TOA solar flux top_flux bins 17–18 still held legacy Fast-JX v7.x values (1.547e16 / 2.131e17). Cloud-J v8.0 restructured bins 17–18 to 345-485-778 nm with fluxes 4.721e16 / 1.488e17.

Because bin 17 (429 nm) contributes ~80% of the J_NO2 integral, the stale flux made J_NO2 ≈ 0.47× the physical value, biasing daytime O₃ low. It also affected J_NO3 (whose v8.0 σ lives entirely in bins 17–18).

Change

Two numeric literals in the existing const top_flux = SA_F32[…] array (bins 17–18 → v8.0). Nothing else.

Why it's safe / minimal

• A scan of all 18-bin cross-sections shows only NO2, NO3, and stratospheric halogens (OClO/BrO/HOBr) have non-negligible bin 17–18 absorption — O₃/HCHO/H2O2/etc. are ≈0 there, so no UV J-value changes.
• The WL effective-wavelength labels are left at 380/574 on purpose: WL is used only to name the F_<wl> actinic-flux variables (never in any J-value computation), and those names appear in golden test references — renaming would break tests for zero physics benefit.

Verification

From-scratch integration (φ=1, TOA): J_NO2 4.26e-3 → 9.17e-3 s⁻¹ (physical clear-sky TOA ≈ 9–10e-3); J_NO3 lands at a physical 0.24 s⁻¹.

Found by a module-by-module equivalence audit of this stack vs GEOS-Chem Classic 14.7.1 / Cloud-J v8.0. Part of the Stage 6 addendum in #225.

---

Update (2nd commit): the same v7.x/v8.0 generation mismatch existed in the bin 17–18 attenuation tables — σ_Raylay[17:18] (Rayleigh ∝ λ⁻⁴; legacy 380/574 nm values over-attenuate the corrected bin-17 flux by ~14% at the surface) and the σ_O3 attenuation rows (Chappuis band at 429/631 nm). Both are now also set to the v8.0 values, completing the bin-17/18 fix. Pinned test values recomputed with the full package; bins 1–16 verified unchanged, and the bin-17/18 changes reproduce the analytic expectation (flux ratio × exp(−Δτ·AMF) = 4.34 / 0.7146) to 3 decimals.

Note for downstream users: FastJX_interpolation_troposphere reads pre-baked fluxes from tropospheric_interpolation_data.bson, which caches values computed with the old tables — that BSON must be regenerated for the interpolation path to pick up this fix (the online FastJX() path picks it up immediately).

Update (3rd commit): the BSON is now regenerated in this PR, so the note above is discharged.
Leaving it out would have made this PR inert for every configuration on the interpolated path —
FastJX_interpolation_troposphere never consults top_flux.

The table ships as a binary with no committed generator, but it reproduces this package's own
direct-beam kernel digit-for-digit at the surface row, so bins 17–18 are moved across by pointwise
ratio transfer rather than by re-deriving the (lost) aloft methodology:

Z_new = Z_old · K_new / K_old        K = direct_solar_beam_box, legacy vs v8.0 bin tables

Checks: bands 1–16 bit-identical; the two kernels' geometric zero sets coincide exactly; wherever
K_old ≠ 0 the transfer is exact to 3.1e-16; key/type layout unchanged so existing BSON.@load
calls are unaffected. Result on the interpolated path at the surface, cosSZA = 1, 298 K:
J_NO2 2.19e-3 → 6.06e-3 s⁻¹.

One residual is deliberately left in place: at a single node per band (P = 50500 Pa,
cosSZA = −0.04, sun ~2.3° below the horizon) both kernels evaluate to zero while the table does
not, so the ratio is undefined there and the legacy entry stays. σ_NO2[18] = 0, so J_NO2 is
untouched; only bin-18 species see it, only in twilight cells.

Worth adding, but not in this PR: a daytime J assertion. Nothing in the suite could have caught
the omission above. fastjx_test.jl only asserts mtkcompile succeeds on the interpolated
operator; geoschem_test.jl checks equation strings; and both composition goldens
(compose_fastjx_superfast_test.jl, pollu_test.jl) sample index 4320 of a 24 h solve, which at
the operators' default coordinates (lat 40 N, long −97 W, t_ref = 0) is cosSZA = −0.35 — the
middle of the night, where every J is identically zero. Changing the table by 2.77× moves
sol_middle by 1.7e-12. O₃ is not a usable probe there either: over the whole 24 h it ranges only
39.9996 … 40.0, so day and night differ by 4e-6 relative, well inside the 1e-4 tolerance. A useful
assertion reads the J values directly at an index that is actually in daylight — j_NO2 (bin-17
dominated) and j_H2O2 (UV bins, independent of this change), plus the night zeros. Happy to send
it as a separate test-only PR; keeping it out of here so this one stays single-topic.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.42%. Comparing base (4cb6241) to head (4b94ca0).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #234   +/-   ##
=======================================
  Coverage   87.42%   87.42%           
=======================================
  Files          20       20           
  Lines        1463     1463           
=======================================
  Hits         1279     1279           
  Misses        184      184           

Flag	Coverage Δ
docs	71.26% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.