engine: C-LEARN data/graph-lookup variables import as 0+0 (zeroed) instead of their lookup/data values

[bpowers]

Summary

A cluster of C-LEARN graphical-function / lookup / data-table-backed series import into the engine with a literal 0+0 equation (or per-element 0+0 | 0+0 | ... for arrayed vars) while the genuine-Vensim reference output (test/xmutil_test_models/Ref.vdf) carries substantial real values. The whole variable is therefore zeroed at runtime. This is the dominant residual cluster in the post-element-cycle-resolution C-LEARN numeric reconciliation (relative error = 1.0 -- entire variables sit at 0 vs real Vensim values).

Discovered during the C-LEARN hero-model work (branch clearn-hero-model, HEAD 8775ae97) after C-LEARN began compiling, running to FINAL TIME, and matching Ref.vdf within 1% on 96.3% of matched cells (following the per-element-GF mapping fix #589 / commit 61573545, and a :NA:-aware + near-zero-robust comparator in ensure_vdf_results). The decision was made to bank the 96.3% and track the residual rather than investigate now: these variables are excluded from the simulates_clearn gate via the documented EXPECTED_VDF_RESIDUAL exclusion constant, so the test passes on the reconciled set. This issue is the tracking item for the largest residual cluster.

Affected variables (representative, not exhaustive)

All from test/xmutil_test_models/C-LEARN v77 for Vensim.mdl. Their imported datamodel equation is literally 0+0 (or 0+0 | 0+0 | ... per element) while Ref.vdf has real values:

• historical_gdp_lookup -- e.g. [cop_developing_b] Vensim = 1.487e5, Simlin = 0
• historical_forestry_lookup
• global_emissions_from_graph_lookup
• ref_global_emissions_from_graph_lookup
• rs_ch4
• rs_hfc125, rs_hfc134a, rs_hfc143a, rs_hfc152a, rs_hfc227ea, rs_hfc23, rs_hfc245ca, rs_hfc32
• other_forcings_smooth_plus_rcp85
• other_forcings_composite_plus_rcp85
• ozone_precursor_forcings
• oc,_bc,_and_bio_aerosol_forcings

These are graphical-function / lookup / data-table-backed series.

Two candidate root causes (not yet determined)

The user chose to track rather than investigate, so the root cause is open. Two candidates:

(a) MDL-import / lowering bug -- a lookup / WITH LOOKUP / graphical-function or GET ...-style data construct is dropped to a 0+0 stub on import. If so, this is a genuine importer defect that silently zeroes real series.

(b) Genuine external-data dependency -- C-LEARN needs external data that is not present, in which case those series cannot match without the data and the 0+0 import may be the correct degradation (no fix to the importer is warranted, only documentation of the missing-data requirement).

The follow-up should determine which by inspecting one representative variable's (historical_gdp_lookup) MDL source in test/xmutil_test_models/C-LEARN v77 for Vensim.mdl and tracing how the importer (src/simlin-engine/src/mdl/) converts it to the 0+0 stub.

Why it matters

• Correctness: if (a), real lookup/data series are silently zeroed on import with no diagnostic -- wrong simulation output cascading through any downstream variable, no crash. This is the single largest source of C-LEARN's divergence from the Vensim reference.
• Diagnosability: a 0+0 stub is indistinguishable at runtime from a legitimately-zero variable; the degradation is invisible without comparing against reference output.

Components affected

• src/simlin-engine/src/mdl/ -- convert/, reader, and the lookup / data-equation handling that emits the 0+0 stub.
• Test fixtures: test/xmutil_test_models/C-LEARN v77 for Vensim.mdl, test/xmutil_test_models/Ref.vdf
• src/simlin-engine/tests/simulate.rs -- simulates_clearn (these vars live in its EXPECTED_VDF_RESIDUAL exclusion const)

Discovery context

Identified during the C-LEARN hero-model element-cycle-resolution work (branch clearn-hero-model, HEAD 8775ae97), element-cycle-resolution AC8.1. These variables are excluded from the simulates_clearn gate and tracked here.

Relationship to existing issues (all DISTINCT)

• engine: per-element graphical functions are mapped by Arrayed-Vec (sorted) position instead of element-name -> dimension index #589 (per-element graphical functions mapped by sorted Vec position instead of dimension index) -- the fix that landed (61573545) and unlocked the 96.3% match; it concerns which element's table is read, not series importing as 0+0.
• engine: C-LEARN full simulation blocked by non-macro issues (circular dep, dimension mismatches, unknown dep) -- the macro epic's deferred 'tracked separately' follow-up #559 (C-LEARN full simulation blocked by non-macro compile issues) -- the compile-blocker tracking item; now resolved (C-LEARN compiles and runs). This issue is a post-run numeric residual, not a compile blocker.
• engine: Vensim :NA: was mishandled as IEEE NaN (should be the finite sentinel -2^109) #586 (:NA: mishandled as IEEE NaN) -- the runtime :NA: sentinel fix; unrelated to lookup/data series zeroing.
• Companion: the smaller residual clusters (SAMPLE UNTIL / INIT-:NA: / numeric tail / NaN-vs-NA) are tracked in a separate umbrella issue.

[bpowers]

The full residual measurement methodology + the three-measurement histogram progression (baseline 28% genuine-divergence → post-GF-fix 3.27% → post-comparator 3.12%, across 873,982 matched cells) — i.e. the quantitative investigation context for this 0+0 cluster and all the residual clusters — is recorded in a comment on the companion umbrella issue #591. This 0+0 cluster is the dominant portion of that 3.12% genuine residual (rel = 1.0, whole variables zeroed).

[bpowers]

Exact EXPECTED_VDF_RESIDUAL membership (measured on clearn-hero-model, un-stubbed simulates_clearn)

The exact exhaustive exclusion set is now baked into EXPECTED_VDF_RESIDUAL in src/simlin-engine/tests/simulate.rs. This 0+0 data/graph-lookup-import cluster accounts for 17 of the 32 excluded bases:

global_emissions_from_graph_lookup, ref_global_emissions_from_graph_lookup, historical_forestry_lookup, historical_gdp_lookup, oc,_bc,_and_bio_aerosol_forcings, other_forcings_composite_plus_rcp85, other_forcings_smooth_plus_rcp85, ozone_precursor_forcings, rs_ch4, rs_hfc125, rs_hfc134a, rs_hfc143a, rs_hfc152a, rs_hfc227ea, rs_hfc23, rs_hfc245ca, rs_hfc32.

These are exactly the variables named in the issue body (the 0+0 whole-variable-zeroed cluster, relative error 1.0). Note: the BARE historical_gdp (without _lookup) is NOT in this cluster -- it imports fine and its only divergence is -2*NA NA-arithmetic cells, so it is attributed to #591 cluster 1 instead. The remaining 15 of 32 excluded bases are #591's SAMPLE UNTIL / NA-arithmetic / numeric-tail clusters.

[bpowers]

Disposition: the engine 0+0 zeroing is FIXED; the residual is now a VDF-reader artifact (tracked in #597)

Closing-recommendation. The engine bug this issue describes (graph-lookup / lookup-only variables importing as a literal 0+0 stub, so the whole variable runs at 0) is resolved.

What was fixed

• Phase 1 (commit 45596177): a lookup-only variable now lowers to gf(Time) (the graphical function applied to Time) instead of the 0+0 stub. The engine's output for every affected base now matches the model's tables byte-for-byte, and every applied consumer of these variables matches Ref.vdf exactly.

So candidate (a) in this issue ("MDL-import / lowering bug dropping a lookup to 0+0") was the real defect, and it is fixed. Candidate (b) ("genuine missing external data") does not apply -- the data is inline graphical-function tables, not external data.

Why these bases still appear in EXPECTED_VDF_RESIDUAL

The remaining divergence for these same bases is not an engine bug. It is a reference-side decode artifact: our Ref.vdf reader mis-decodes the standalone graphical-function ("lookup-only") descriptor columns (the engine value is correct; the reference column we read is wrong). This is now tracked precisely in #597, which supersedes this issue's "engine 0+0" framing:

• The scalar half of the reader decode was fixed in commit d69754bc (standalone_descriptor_rebinds, proven byte-exact for global_emissions_from_graph_lookup -> OT 1612, which has dropped out of the carve-out).
• The arrayed half (13 bases: historical_forestry_lookup, historical_gdp_lookup, rs_ch4, rs_co2_ff, rs_gdp_in_trillions, rs_hfc125, rs_hfc134a, rs_hfc143a, rs_hfc152a, rs_hfc227ea, rs_hfc23, rs_hfc245ca, rs_hfc32) plus 4 scalar no-distinct-column cases (ref_global_emissions_from_graph_lookup, ozone_precursor_forcings, oc,_bc,_and_bio_aerosol_forcings, other_forcings_smooth_plus_rcp85) are tracked in engine: VDF reader mis-decodes arrayed standalone graphical-function ("lookup-only") descriptor columns (Ref.vdf) #597.

Recommendation

The engine correctness bug is resolved -- recommend closing this issue and letting #597 carry the reference-reader decode work. (Filing this as a comment rather than auto-closing so a human can confirm the disposition.) These 17 bases remain in tests/simulate.rs::EXPECTED_VDF_RESIDUAL as documented VDF-decode-artifact carve-outs, each with a one-line sourced reason, guarded for exactness by clearn_residual_exactness.