Agents4GEOS: An Agent Team That Builds Physics Simulations

The bottleneck nobody writes papers about

Scientific computing has a glamorous front and a tedious back. The glamour is the physics, the plume of carbon dioxide creeping through porous rock, the pressure building against a distant aquifer. The tedium is getting the simulator to accept your description of that physics in the first place. Powerful open source simulators like GEOS earn their power through flexibility, and that flexibility is paid for in configuration. Every solver, every fluid model, every mesh and well and boundary must be spelled out in a long input file where names in one section must exactly match targets in another.

Authoring and debugging those files by hand is slow, error prone, and a real barrier to entry for newcomers. Worse, it is a recurring tax on exactly the workflows that modern reservoir science depends on, the many query problems like uncertainty quantification and history matching that require running the same simulation over and over with slightly different parameters. If you want to train a fast machine learning surrogate to stand in for the expensive simulator, you first need to generate hundreds of those runs, which means authoring hundreds of those files. The bottleneck is not the physics or the compute. It is the plumbing.

Agents4GEOS attacks the plumbing. It reframes the whole task as a conversation. You describe the simulation you want in plain English, and a team of specialized agents collaborates to produce a schema valid, physically sensible input file, backed by real fluid property and meshing calculations rather than by a model guessing at plausible text.

The one rule that makes it trustworthy

Here is the design decision that matters most, and it is the reason a system like this can be trusted with quantitative science at all. The architecture enforces a strict separation of concerns across three roles. Agents plan and decide, but perform no arithmetic. Tools carry out every concrete computation, deterministically. And versioned knowledge files hold the domain patterns, the valid field names and constitutive assemblies and physics sanity rules. The authors state the principle in one line, tools do the work, knowledge encodes domain expertise, and agents decide what work to do.

The point of that division is to slam the door on the failure mode that makes people nervous about language models in science, the confident invention of a number that looks right and is wrong. In Agents4GEOS a fluid density or a mesh block is never emitted by the model as text. It is returned by a tool that actually computed it, using an established scientific library. The agent chooses which tool to call and interprets the result, but the value itself is grounded in real computation. This is the same reliability instinct that shows up across agentic science, including our look at an agentic AI that operates a synchrotron beamline, where a model reasons about an instrument but the instrument does the measuring.

Tools do the work, knowledge encodes domain expertise, and agents decide what work to do. Every quantity handed back to the user is the result of an actual computation, not a plausible sentence.The guiding principle of Agents4GEOS

A layered team, built on the Model Context Protocol

Concretely, the system is organized as four layers, and it runs on infrastructure that will be familiar to anyone following the agent tooling world. It is implemented as a server speaking the Model Context Protocol, the emerging open standard through which a model discovers and calls external tools, and it is operated by the Claude Code harness that runs the agent loop.

At the top, the user speaks only natural language. Below that sits the agent layer, eleven role specialized agents plus four fresh context subagents. A single orchestrator converses with the user and delegates to specialists for schema queries, fluid properties, meshing, validation, running, post processing, and even curating error logs. The four subagents are dispatched with a clean slate, sharing none of the orchestrator’s conversation, and they return structured results checked against a rigid contract rather than free form text. Beneath the agents, the tool layer holds 52 stateless tools grouped into six domains, each backed by a real scientific library, and these do all the actual work. At the base, a foundation layer holds the scientific engines and the knowledge files distilled from an audit of more than two hundred official GEOS input files.

Paying only for the intelligence you need

A neat cost idea runs through the agent layer. Every agent carries a capability tier that reflects how hard its job is, from simple retrieval, through synthesis, to full multi step planning. The policy is to route each job to the cheapest model that can reliably do it, and to move up a tier only when a cheaper model would be unreliable, on the reasoning that a wrong answer costs far more than the savings. The specialized subagents pin the model that matches their tier, so routine mesh and fluid computations run on a mid sized model while the all important independent review runs on the most capable one. As models get cheaper and better over time, a subagent can quietly drop to a lower tier without any change to its definition.

The reviewer who was not in the room

The cleverest agent is the independent reviewer. After the team assembles a simulation, a fresh reviewer agent examines it with no memory of how it was built, checking not just that the file is valid but that it faithfully matches what the user actually asked for, the injection rates, the run duration, the domain size. Because it shares none of the builder’s context, it can catch a drift from the original intent that the builder, invested in its own work, might miss. If the reviewer finds a blocking problem, the orchestrator fixes the deck and dispatches a brand new reviewer, up to three rounds. It is an assembly line with an inspector who never gets attached to the product.

Watching it reproduce a benchmark from one sentence

The clearest way to see what this buys you is the demonstration the authors walk through. A reservoir engineer asks, in plain English, to reproduce a published carbon storage benchmark, handing the system only the two source papers as PDF files and a set of mesh and well files. Everything after that happened in a single session lasting about an hour and consuming roughly 343 thousand tokens, during which the user wrote no XML and no shell commands.

The orchestrator framed the job as extraction then translation. It sent two paper mining agents to read the two PDFs in parallel, each returning a quote backed specification, while it inspected the provided files itself. Out came the grid dimensions, the fluid system, the relative permeability endpoints, the injection program of eight wells over ten years followed by centuries of migration. More impressively, the local inspection showed real understanding. It spotted a physically impossible porosity value on the boundary cells and correctly recognized it as a modeling trick that represents an open aquifer boundary, and it noticed that the benchmark had deliberately relocated the reservoir to a shallower depth to hit a target initial pressure.

Then it did something a good collaborator does. Rather than guess at the ambiguous scientific choices, it returned to the user a short list of three real decisions, each with a recommendation and its tradeoff, about how to represent the fluid system, where to place the formation, and how to reconstruct the property tables. The user approved all three. This is the human in the loop contract the authors describe, the system decides everything it can from the sources, the code, and sensible defaults, and reserves the user’s attention for the genuine scientific judgment calls.

Honesty as a designed behavior

The part of the demo most worth dwelling on is what happened when the two source papers disagreed. The injection rate stated in one paper and the rate implied by the other differed by more than a factor of ten. A careless pipeline would silently pick one and move on. Agents4GEOS instead re queried both paper mining agents for verbatim quotes, traced the tension to a subtle definition of pore volume, kept the literal value from its stated reproduction target, and reported the discrepancy to the user rather than hiding it. That behavior was not an accident. It was enforced by the agent’s written instructions.

This runs deeper than a single number. When the simulator rejected the first assembled file twice, for errors that only surface at run time, the system diagnosed each, fixed it, and wrote the lesson into its error knowledge base so the next run would benefit. One failure was a geometric mismatch where the wells were positioned a meter below where they should be, which the agent resolved by parsing the mesh and computing the true cell depths. The other was a quirk of the simulator’s own naming rules. A learning loop that turns yesterday’s run time failure into tomorrow’s avoided mistake is exactly the kind of institutional memory that agentic systems can accumulate, a theme we explored in our coverage of an LLM agent that meta learns simply by being used.

The final run completed in under three minutes and produced a hundred and one snapshots of the evolving reservoir. When the user questioned which observation point a saturation curve used, the orchestrator openly admitted it had taken a shortcut by plotting the domain maximum, then went back and extracted the true values at the three fixed observation cells the benchmark specifies. The resulting curves matched the published reference precisely, the crest cell holding its gas while the flank cells drained back toward zero.

That endpoint, the maximum gas saturation the rock will hold as brine drains away, is the kind of physical quantity the whole edifice exists to get right. It was reproduced not because a model recalled it, but because the tools computed it and an independent reviewer checked it.

From one simulation to a fast forecaster

A single validated simulation is only the beginning. The real prize is scale. By running the same agent built scaffold across two hundred variations of the rock’s permeability, the team generated a physically consistent dataset, one hundred simulations for training and one hundred for testing, of exactly the kind that machine learning surrogates need. Crucially, they validated these agent generated simulations against results from two other established simulators, lending confidence that datasets built this way at scale are trustworthy.

On that dataset they trained a graph neural network surrogate named Plumecast. It treats the reservoir mesh as a graph, with cells as nodes and their neighbor relationships as edges, and learns to roll the simulation forward in time, informed by real reservoir physics baked into its features. The result reproduces the movement of the carbon dioxide plume at long time horizons and a small fraction of the cost of full simulation. This graph based, physics informed approach to accelerating a simulator is a fast growing corner of scientific machine learning, and it rhymes with our look at a graph network that forecasts molecular dynamics and at a neural operator that solves moving boundary problems. The novelty here is that the entire pipeline, from a natural language description to a trained surrogate, is stitched together by agents.

Honest limitations

The authors are clear about what remains unsolved, and the limitations are the practical kind. Meshing genuinely complex reservoirs is hard and, they argue, deserves its own dedicated specialist agent that does not yet exist. Launching and babysitting long jobs on computing clusters needs more robust coverage before every run can be trusted to finish. And interacting with a simulation while it runs, watching it converge, diagnosing when it stalls, steering or restarting it midway, is still an open frontier the current system does not address.

One limitation is a sign of the times. Token usage, the authors note, has become a meaningful line in the budget, no longer a rounding error next to the processor and graphics hours a simulation consumes. When a single reproduction session spends hundreds of thousands of tokens, the cost of the thinking starts to matter alongside the cost of the computing. They also point to a broader gap in the field, that existing benchmarks for agentic AI barely cover subsurface engineering at all, which makes it hard to measure progress rigorously. None of these caveats undercuts the demonstration. They map the road from a promising prototype to a dependable tool, and the authors are candid that this is the first stage of a longer roadmap toward fully automated surrogate construction.

The core architecture, in runnable Python

The block below is a faithful, self contained reference implementation of the architecture’s spine, namely a stateless tool layer, fresh context subagents that return results validated against typed contracts, an orchestrator that runs the four coordination patterns the paper describes, a knowledge module lookup, and the independent reviewer with its bounded feedback loop. The language model and the scientific libraries are stubbed so the whole thing runs offline. It follows the design described in the paper rather than reproducing the authors’ code.

# Agents4GEOS architecture: agents decide, tools compute, knowledge encodes.
# Coordination patterns: pipeline, fan-out, feedback loop, quality contract.
from dataclasses import dataclass
from concurrent.futures import ThreadPoolExecutor

# ----------------------------------------------------------------------
# 1. Knowledge modules: the single source of truth for domain patterns
# ----------------------------------------------------------------------
KNOWLEDGE = {
    "routing": {"co2": "co2_brine", "oil": "dead_oil", "thermal": "thermal"},
    "fluid_models": {"co2_brine": "CO2BrinePhillipsFluid", "dead_oil": "DeadOilFluid"},
    "valid_fields": {"DeadOilFluid": {"pressure", "globalCompFraction"}},
    "banned_colormaps": {"rainbow", "jet"},           # quality contract enforces this
}

# ----------------------------------------------------------------------
# 2. Stateless deterministic tools: every quantity is computed, not invented
# ----------------------------------------------------------------------
def recommend_fluid_model(scenario):
    key = next((k for k in KNOWLEDGE["routing"] if k in scenario.lower()), "co2")
    return KNOWLEDGE["fluid_models"][KNOWLEDGE["routing"][key]]

def compute_brine_properties(temp_c, salinity=0.1):
    # stand-in for a real PVT library call (pyResToolbox in the paper)
    density = 1000 + 700 * salinity - 0.4 * temp_c    # kg/m3, SI units
    viscosity = 0.001 * (1 + 1.5 * salinity)          # Pa.s
    return {"density": round(density, 1), "viscosity": round(viscosity, 5)}

def validate_cross_references(deck):
    fluid = deck.get("fluid_model")
    ok = KNOWLEDGE["valid_fields"].get(fluid, set())
    bad = [f for f in deck.get("fields", []) if f not in ok]
    return (len(bad) == 0, bad)

# ----------------------------------------------------------------------
# 3. Typed contracts: a subagent result that violates its contract is rejected
# ----------------------------------------------------------------------
@dataclass
class FluidResult:
    model: str
    density: float
    viscosity: float
    def valid(self): return self.density > 0 and self.viscosity > 0

@dataclass
class MeshResult:
    nx: int; ny: int; nz: int
    def valid(self): return min(self.nx, self.ny, self.nz) > 0

# ----------------------------------------------------------------------
# 4. Fresh-context subagents (agents decide which tools to call)
# ----------------------------------------------------------------------
def geos_fluids(scenario, temp_c):
    model = recommend_fluid_model(scenario)
    props = compute_brine_properties(temp_c)
    return FluidResult(model, props["density"], props["viscosity"])

def geos_mesh(nx, ny, nz):
    return MeshResult(nx, ny, nz)

def geos_reviewer(deck, intent):
    # independent review with no builder context: schema + intent fidelity
    findings = []
    ok, bad = validate_cross_references(deck)
    if not ok: findings.append(f"unresolved fields: {bad}")
    if deck.get("years") != intent.get("years"):
        findings.append("run duration does not match stated intent")
    return findings

# ----------------------------------------------------------------------
# 5. Orchestrator: fan-out, pipeline, and a bounded feedback loop
# ----------------------------------------------------------------------
def orchestrate(request, intent, max_review=3):
    # fan-out: dispatch compute subagents in parallel
    with ThreadPoolExecutor() as ex:
        f_fluid = ex.submit(geos_fluids, request, intent["temp_c"])
        f_mesh = ex.submit(geos_mesh, *intent["grid"])
    fluid, mesh = f_fluid.result(), f_mesh.result()
    for r in (fluid, mesh):                        # reject contract violations
        if not r.valid(): raise ValueError(f"contract violated: {r}")

    # pipeline: assemble the deck from validated fragments
    deck = {"fluid_model": fluid.model, "grid": (mesh.nx, mesh.ny, mesh.nz),
            "fields": intent["fields"], "years": intent["years"]}

    # feedback loop: independent review, fix, and re-review (bounded)
    for _ in range(max_review):
        findings = geos_reviewer(deck, intent)
        if not findings: return deck, "VALIDATED"
        # orchestrator applies a fix, then dispatches a FRESH reviewer
        deck["fields"] = [f for f in deck["fields"]
                          if f in KNOWLEDGE["valid_fields"].get(deck["fluid_model"], set())]
        deck["years"] = intent["years"]
    return deck, "UNRESOLVED after max review iterations"

# ----------------------------------------------------------------------
# 6. Run: one sentence -> a validated simulation deck
# ----------------------------------------------------------------------
if __name__ == "__main__":
    request = "Reproduce a dead-oil CO2 sequestration case"
    intent = {"temp_c": 40, "grid": (19, 28, 5), "years": 500,
              "fields": ["pressure", "globalCompFraction", "badName"]}
    deck, status = orchestrate(request, intent)
    print("status:", status)
    print("deck:", deck)                              # 'badName' removed by the review loop
    print("smoke test ok")

Conclusion

The central contribution of Agents4GEOS is architectural discipline. It takes the exciting but slippery idea of a language model running a scientific workflow and makes it dependable by refusing to let the model do the one thing it does badly, produce quantitative facts. By separating deciding from computing from remembering, and by wiring an independent reviewer between the work and the user, it converts a fallible reasoning engine into a reliable collaborator for a domain where a wrong number is worse than no number.

The reproducibility demonstration is the proof that this works in anger. Turning two dense source papers and a one sentence request into a validated simulation that matches a published benchmark, in about an hour and with no hand written configuration, is a concrete and impressive result. What elevates it is the conduct along the way, the system asking a human about the three genuine scientific choices while handling everything mechanical itself, and above all reporting a real contradiction between its sources rather than smoothing it over. Honesty as an enforced behavior is the quality most needed and least common in automated science.

The pipeline does not end at a single run. By generating hundreds of consistent simulations and validating them against other simulators, the team turned its agents into a data factory for a graph neural network surrogate that forecasts carbon plume movement cheaply. That end to end path, from a plain sentence to a trained fast model, is where the practical value lies, because it attacks the many query problems that make subsurface engineering so expensive.

The honest limitations keep the claim grounded. Complex meshing wants its own agent, long cluster runs need firmer handling, live steering of a running simulation is unaddressed, and the token bill is now large enough to notice. These are the ordinary frictions of a first stage system, and the authors present a clear roadmap past them rather than pretending they are solved.

Read as a finished product, this is a prototype. Read as a blueprint, which is how to let language model agents do real quantitative science without letting them invent the science, it is one of the more convincing answers available. For the broad project of putting agents to work on hard technical problems, the recipe here, decide with the model, compute with tools, remember in versioned knowledge, and always keep an independent check, is worth copying far beyond the study of rock and carbon.