Human review: compare the Codon port and RecastEngine's NumPy translation of the same routines

[chenyueqi]

Context

Branch recast-gate adds a module-level bit-exactness harness driven by RecastEngine (see test/recast/README.md). Running it on one routine produced a three-way result worth a human look:

comparison	result
Codon port vs native Fortran	bit_exact — 43200/43200 points, 0 ULP
engine's NumPy translation vs native Fortran	bit_exact — 43200/43200 points, 0 ULP
engine's NumPy translation vs Codon port	bit-identical, 43200 points across 120 output arrays

So for this routine there are now two independent modernizations that agree with the original to the last bit — one written by the LLM-agent pipeline in this repository, one produced mechanically by RecastEngine's rule-driven translator. They are very different code. What the machine cannot judge is which properties matter for CAM going forward, and that is the ask below.

The ask

@cnitlrt — could you read the two generated implementations side by side and give an opinion? Not a correctness review (the gate covers that) but a judgement call: what does each path give up, and where would you want which?

Pair 1 — the routine already gated

• native Fortran: src/physics/cam/vertical_diffusion.F90, vertical_diffusion_ptend_core_native, lines 2125–2159
• Codon port: src/physics/cam/vertical_diffusion_codon.py, vertical_diffusion_ptend_core_codon, from line 588 (body from line 613)
• engine's NumPy: not committed (it is generated). To produce it:

pip install -e ../RecastEngine'[fortran,translate,verify]' -e ../recast-cesm
clang -c -fPIC -O1 -o test/recast/build/vd_callback_stubs.o test/recast/vd_callback_stubs.c
codon build --relocation-model=pic -release --lib \
    --linker-flags="$PWD/test/recast/build/vd_callback_stubs.o" \
    -o test/recast/build/libvertical_diffusion_codon.dylib \
    src/physics/cam/vertical_diffusion_codon.py
python test/recast/run_threeway.py
# then read:
#   test/recast/work-threeway/engine/candidate/vd_ptend_core_numpy.py

The visible differences on this routine:

	Codon port	engine's NumPy
loops	explicit for k / for i / for m, 1-based, range(1, pver + 1)	vectorized [:ncol, :] slices
addressing	hand-linearized _idx2(i, k, pcols) / _idx3(...) (definition near line 326), column-major arithmetic written out	NumPy multi-dimensional indexing, 0-based
out arguments	written through pointers in place, no return value	intent(out/inout) become a returned tuple
dimensions	passed explicitly (pcols, pver, pcnst, psetcols)	read from a generated constants module; shapes carry the rest
provenance	none	every statement carries # B00N <- L45-L45 back to the Fortran line

Both produce the same bits here. That is not automatic — it holds because this routine is elementwise with no reduction, so no summation order can differ. Which brings the interesting question:

Pair 2 — where the two paths would be expected to diverge

dadadj is the opposite shape: iterative, converging, numerically fragile.

• native Fortran: src/physics/cam/dadadj.F90, dadadj_native, from line 122
• Codon port: src/physics/cam/dadadj_codon.py, dadadj_codon, from line 29
• engine's NumPy: RecastEngine currently refuses this routine — test/recast/run_gate.py gates the Codon port against Fortran (9600/9600 bit-exact), but the translator defers one block, reporting:

dadadj_native/B004: goto 80 is not a loop-exit pattern

The two F77 gotos in dadadj_native — go to 80 jumping to the terminator of the labelled do 80 i=1,ncol (a cycle) and the backward go to 50 (a retry with doubled zeps) — have no mechanical rewrite in the translator yet. Per the plan discussed, those rules will be added upstream in CESM-language-translator and retrieved from there rather than invented here.

Questions worth your judgement

1. Readability / maintainability. If someone has to debug a wrong number in three years, which of the two would you rather be holding? Does the engine's block-marker provenance (# B004 <- L48-L48) earn its keep, or is _idx2(i, k, pcols) clearer about what the memory is doing?
2. Where vectorization is a trap. The NumPy form is bit-identical for elementwise work. For which CAM routines would you expect it to stop being — reductions, iterative solvers, anything where FMA contraction or SIMD reassociation can bite? Two more pure candidates to look at if useful: macrop_driver.F90 / macrop_driver_detrain_init_shell_native (line 1704, Codon at macrop_driver_codon.py:3931) and physpkg.F90 / tphysbc_init_fields_native (line 7220).
3. Whether a second path is worth having at all. The Codon path is the one that ships — it links into CAM and keeps the calling interface. The NumPy path is standalone and cannot. Is a mechanically-generated, provenance-carrying NumPy version useful to you as a cross-check on the Codon port, as documentation, or not at all?
4. The goto rules. When you add the cycle / backward-retry rules to CESM-language-translator, do the shapes in dadadj_native generalize, or is that routine's control flow unusual enough to be worth its own note?

Notes

• A survey of this repository's 32 Codon-ported files found 49 routines that are pure (no module state read or written, no calls) and therefore gateable with no setup, so this harness extends by pointing it at another name.
• The gate's inputs are physically ranged but synthetic, not sampled from a model run. Both paths agreeing here means they agree on the sampled region, not that the region CAM actually visits was covered — captured dumps are the honest next step.
• Nothing under src/ was modified on recast-gate; the branch adds only test/recast/.

[cnitlrt]

1. Readability and maintainability

From a readability and long-term maintenance perspective, I prefer the NumPy form generated by RecastEngine. It preserves array expressions close to the original Fortran and can carry provenance similar to debugging information. The current markers already map generated code back to input statements. If they are extended to record the original routine, file, and exact translation rule, then common cases covered by the translator can be maintained primarily by updating the rule base and regenerating the code. The smaller set of cases that cannot be expressed safely by general rules can still be handled manually or with LLM assistance. As rule coverage grows, the Recast path should ideally become more manageable to maintain.

The Codon organization is not always one-to-one with the Fortran organization: related helpers may be split, combined, or repeated across Codon modules. This can make source tracing and synchronized changes more expensive as the port grows.

For this specific question, a block marker earns its keep only if it is tied to a source revision or digest and regenerated when the Fortran changes. A bare # B004 <- L48-L48 can become stale as source lines move and may then make debugging harder. _idx2(i, k, pcols) exposes memory addressing, but it is not self-explanatory to someone who has not read its definition. The marker is therefore more useful for source tracing, while _idx2 is more useful for checking memory layout;

2. Where vectorization is a trap

I would use a conservative translation rule that preserves the form of the original Fortran: keep explicit Fortran loops as loops with the same execution order, and translate Fortran array expressions into corresponding NumPy vectorized expressions. This avoids accidentally vectorizing a loop with a loop-carried dependency. Even when the original Fortran already uses array expressions, however, the Fortran compiler and NumPy may use different floating-point optimizations or execution strategies, so bitwise identity should not be assumed without sufficiently broad bit-exact testing.

3. Whether a second path is worth having at all

I think it is worth keeping. Even though the NumPy path cannot currently be tested inside CESM, it can still serve as a module-level unit-testing and cross-checking tool, but not as a second production implementation.

The generated NumPy code cannot currently link into CAM and therefore cannot replace whole-CAM testing. Its value is as an independent third result that helps triangulate failures. Assuming exactly the same inputs:

• If NumPy agrees with native Fortran but Codon does not, I would first investigate the Codon port, build configuration, ABI, pointer handling, and array addressing.
• If Codon agrees with native Fortran but NumPy does not, I would investigate RecastEngine’s translation rules and the generated dtype, shape, and NumPy runtime semantics.
• If all three agree in the standalone gate but the Codon-enabled CAM run diverges from native CAM, I would investigate differences in compiler settings, including FMA contraction, SIMD reassociation, and fast-math.

I therefore see NumPy as an independent witness and executable debugging reference, rather than a replacement for the Codon implementation. If feasible in the future, a corresponding bridge could be added to connect the NumPy path to a real CESM run for integration-level testing.

4. Whether the goto rules generalize

I used Codex to perform a source-level scan:

Scope	GOTO to labelled-DO terminator	Terminator is continue	Backward GOTO	Backward GOTO directly to DO
src/physics/cam (119 files)	3	3	2	1
Full CAM src/	42	41	59 (31 routines)	1 (dadadj only)

Relative to the size of the CAM source tree, these GOTOs are uncommon. I would therefore not add a special-case rule for dadadj at this stage. It can remain deferred or be handled manually, and a general rule can be reconsidered if the same structured pattern appears repeatedly in the future.