🤖 AI

Systematic LLM Translation of Legacy Scientific Code to Differentiable Frameworks: Application to a Land Surface Model

This paper presents a five-phase LLM-based agentic pipeline that successfully translates a 19,000-line legacy Fortran land surface model into a differentiable JAX framework, achieving significant performance gains in parameter recovery and computational speed while ensuring numerical parity through automated error correction and verification.

Original authors: Aya Lahlou, Linnia Hawkins, Pierre Gentine

Published 2026-06-09

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Aya Lahlou, Linnia Hawkins, Pierre Gentine

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you have a massive, incredibly complex, and slightly dusty old library of instructions written in a forgotten language (Fortran). This library tells a computer exactly how to simulate the Earth's land surface—how plants breathe, how soil heats up, and how water moves. It's been running for decades, and it works perfectly, but it's "legacy" code: it's hard to read, hard to change, and it can't easily learn from new data.

The authors of this paper wanted to take this old library and translate it into a modern, super-smart language (JAX) that allows the computer to not just run the simulation, but to learn from it. They built a team of AI agents (digital workers) to do this translation automatically.

Here is how they did it, explained through simple analogies:

1. The Problem: The "Black Box" Library

The old code is like a giant, tangled ball of yarn. If you want to change one thread (a parameter), you have to pull the whole thing apart to see what happens. Also, the old code can't tell you why a result happened or how to tweak it to get a better result. It just gives you an answer.

2. The Solution: The "Five-Phase AI Construction Crew"

Instead of hiring a human to rewrite the whole thing (which would take years), the authors created a five-step automated pipeline using Large Language Models (LLMs). Think of this as a construction crew with specific roles:

Phase 1: The Architect (Dependency Analysis)
Before building anything, the AI reads the entire blueprint to understand how the rooms connect. It figures out which parts of the code depend on which other parts. This ensures they translate the code in the right order (like building the foundation before the roof) so nothing gets lost.
Phase 2: The Project Manager (State Documentation)
The AI creates a digital "logbook" (files like plan.md and CHANGELOG.md). If the AI gets stuck or makes a mistake, it writes it down. This acts as the crew's memory, so if the AI takes a break or restarts, it knows exactly where it left off and what went wrong last time.
Phase 3: The Quality Control Inspector (Fortran Oracle)
This is the most critical step. The AI translates a small chunk of the old code into the new language. Then, it runs both the old version and the new version side-by-side with the exact same inputs. It checks: "Do the numbers match perfectly?" If the new code says "5.0" and the old code says "5.0001," the AI knows it made a mistake and has to fix it.
Phase 4: The Repair Loop (Iterative Translation)
If the Quality Control Inspector finds a mismatch, the AI doesn't give up. It enters a "repair loop." It reads the error, guesses what went wrong, fixes the code, and tests it again. It does this over and over until the numbers match perfectly. The paper found that this AI crew could fix about 81% of its own mistakes without human help.
Phase 5: The Final Assembly & Stress Test (Integration & Differentiability)
Once all the small chunks are translated and tested, the AI stitches them together into one big model. Then, it performs a special "stress test" to ensure the model can calculate gradients (slopes).
- Analogy: Imagine driving a car. The old code could tell you where you are. The new code can tell you exactly which way to turn the steering wheel and how hard to press the gas to get to your destination faster. This is what "differentiable" means.

3. The Results: What Did They Achieve?

They applied this process to a 19,000-line land surface model (CLM-ml-v2). Here is what happened:

Perfect Translation: The new AI-translated model produced results that were mathematically identical to the old Fortran model. It wasn't an approximation; it was a perfect clone.
Super Speed: When they ran the model on a computer chip designed for AI (a GPU) with thousands of different scenarios at once, it was 24 times faster than the old code running on a standard processor.
Learning Speed: When they tried to tune the model to find the best settings (parameter estimation), the new model found the answer in 8 times fewer steps than the old methods. It's like finding a needle in a haystack by using a magnet instead of looking at every piece of hay one by one.

4. Why This Matters

The paper shows that we don't need to throw away our decades of scientific work to use modern AI. We can use AI to translate our old, trusted scientific code into a new format that is just as accurate but much faster and capable of learning.

The authors released their "construction crew" (the pipeline) and the translated model as open tools, hoping other scientists can use this same method to upgrade their own old scientific software.

In short: They built a robot team that read an old, dusty instruction manual, rewrote it into a modern language, double-checked every single word to ensure it was perfect, and proved that the new version works 24 times faster and can learn from data much better than the old one.

Technical Summary: Systematic LLM Translation of Legacy Scientific Code to Differentiable Frameworks

Problem Statement
Legacy Earth System Models (ESMs), particularly land surface models (LSMs), are critical for climate policy and forecasting but remain largely inaccessible to modern differentiable programming techniques. These models, often comprising hundreds of thousands of lines of Fortran code, suffer from poor modularity, deprecated components, and a shrinking developer workforce. While differentiable programming enables efficient gradient-based parameter estimation, sensitivity analysis, and data assimilation, migrating legacy codebases to differentiable frameworks (like JAX) remains an unsolved challenge. Existing attempts at code modernization either involve clean rewrites that discard legacy physics or fail to scale beyond isolated functions due to cross-file dependencies and the lack of numerical fidelity in Large Language Model (LLM) translations. Furthermore, current LLM benchmarks do not adequately measure the scientific validity or numerical parity required for physical models.

Methodology: A Five-Phase Agentic Pipeline
The authors propose a systematic, five-phase agentic pipeline to translate the 19,000-line, 102-module Fortran land surface model CLM-ml-v2 into a fully differentiable JAX implementation named clm-ml-jax. The pipeline relies on three core design principles: static dependency analysis, modular numerical parity testing, and comprehensive gradient verification.

Phase 1: Scoping and Dependency Analysis: To prevent LLM hallucinations regarding data types in coupled codebases, the authors perform static analysis on the full module dependency graph. A topological sort determines a dependency-respecting translation order, ensuring that all imported modules are translated before the modules that depend on them.
Phase 2: State Documentation Setup: The pipeline utilizes persistent state documents (CLAUDE.md, plan.md, CHANGELOG.md) to serve as external agent memory. These documents encode project conventions, track completion flags, and log failed attempts, enabling coherent session resumption across context-window boundaries and preventing agents from revisiting dead-ends.
Phase 3: Fortran Oracle Construction: Before translation, a team of agents constructs a functional test suite. Subroutines are classified into three tiers based on testability. The system executes the original Fortran code under fixed inputs to generate "golden" input-output pairs, establishing a reference oracle for numerical validation.
Phase 4: Iterative Translation, Testing, and Repair: Modules are processed in the topological order established in Phase 1. A translator agent generates JAX code, which is then validated by a testing agent against the Fortran oracle (requiring relative tolerance within $10^{-4}$ ). If a test fails, a "Ralph Loop" (an orchestration pattern) engages a repair agent to diagnose discrepancies, edit the code, and re-test autonomously until the module passes or is flagged for human review.
Phase 5: Integration and Differentiability Validation: Once modules are translated, an Integration Agent assembles the full column pipeline and validates end-to-end behavior. A Differentiability Agent then iteratively resolves JAX-specific issues, such as:
- Static Loop Unrolling: Replacing Python-level for loops with jax.lax.scan to trace loop bodies once at compile time, avoiding unmanageable computation graphs for Runge-Kutta solvers.
- Static vs. Dynamic Typing: Converting constants to JAX scalars to prevent full recompilation caused by changing cache keys.
- Branch-Safe Guards: Applying lower bounds (e.g., jnp.maximum(x, 1e-30)) to prevent NaN gradients from operations like $0 \times \infty$ in jnp.where expressions.
- Implicit Function Theorem (IFT) Adjoins: Differentiating iterative solvers (e.g., stomatal conductance bisection, Monin–Obukhov length) using IFT adjoints rather than unrolling the loop, which yields incorrect gradients.

Key Results
The resulting clm-ml-jax model was evaluated on the CHATS7 walnut orchard AmeriFlux site using May 2007 meteorological data.

Numerical Equivalence: The translated model achieved near-perfect numerical parity with the Fortran reference across 1488 timesteps, with correlation coefficients of 1.000 and negligible bias for all variables (e.g., sensible heat, latent heat, GPP).
Gradient Correctness: Reverse-mode differentiation was validated against central finite differences. All active parameters achieved relative errors less than $1 \times 10^{-4}$ . The pipeline successfully handled complex structures, including iterative solvers and Runge-Kutta sub-steps.
Parameter Calibration Efficiency: In a proof-of-concept calibration of three parameters, the gradient-based L-BFGS-B optimizer recovered ground-truth values to machine precision ( $\sim 10^{-19}$ ) in fewer than 50 evaluations. This was 8 times faster (in terms of evaluations) than the gradient-free Nelder-Mead optimizer.
Performance Speedup: Using jax.vmap on a GPU (Quadro RTX 8000), the model achieved a 24x wall-clock speedup over sequential Fortran execution at an ensemble size of $N=2,048$ . The amortized cost per sample dropped from 24.9 ms to 11.4 ms as ensemble size increased, whereas Fortran remained flat at $\approx 54$ ms/sample.
Agentic Efficiency: Across 73 module translation tasks and 46 agentic sessions, 81.2% of bugs were resolved autonomously on the first attempt. Total human oversight was estimated at only 10–15 hours.

Significance and Claims
The paper claims to demonstrate that legacy scientific codebases can be systematically translated into fully differentiable frameworks without manual re-implementation, preserving scientific ground truth.

Scientific Payoff: The work enables gradient-based parameter optimization and sensitivity analysis that were previously intractable for CLM-ml-v2. The Jacobian analysis reveals that air temperature and shortwave radiation dominate sensitivities of Gross Primary Production (GPP) and energy fluxes, while $V_{c,max}$ exerts distinct control.
Methodological Contribution: The paper presents a reproducible, five-step workflow with autonomous repair loops and domain-specific oracle validation. It quantifies the feasibility of "co-authorship" between humans and AI agents in scientific code modernization, showing that high-level human oversight is sufficient for complex, multi-day translation tasks.
Reusability: Both the translated model and the pipeline infrastructure are released as a reusable framework, intended to support the community in differentiating other Earth system model components.

The authors position this work not as a final solution for all ESMs, but as a validated proof-of-concept that bridges the gap between legacy Fortran physics and modern differentiable programming, paving the way for hybrid physics-ML architectures and more efficient uncertainty quantification in climate modeling.

1. The Problem: The "Black Box" Library

2. The Solution: The "Five-Phase AI Construction Crew"

3. The Results: What Did They Achieve?

4. Why This Matters

Technical Summary: Systematic LLM Translation of Legacy Scientific Code to Differentiable Frameworks

More like this