DREAMS: Density Functional Theory Based Research Engine for Agentic Materials Simulation

In plain words

Language-model agents can run long scientific calculations on their own, but the numbers they produce can look right and still be wrong. An agent can lose track of earlier steps, skip a check, or copy a value from one place and present it as the result of a calculation. DREAMS is a set of cooperating agents that set up and run materials simulations on a computer cluster, with one extra layer: every number an agent uses has to be traceable to the tool call that produced it, and a checker must approve each setting before it is used.

The checks combine simple rules, which are applied wherever a clear pass/fail test exists, with judgments from a language model for everything else. A shared notebook-like memory holds the intermediate results, and a final reviewer walks back from each reported number to the settings behind it. The authors report that the checks catch values that were not really computed, at the price of many more model calls and tokens. The method is tested on lattice-constant and surface-adsorption problems in solid-state physics.

TL;DR

• A hierarchical LLM system (planner, DFT agent, HPC agent, convergence agent) drives Quantum ESPRESSO for periodic solid-state DFT.
• Every tool output is registered with a provenance record. A guard checks each tool call before it runs, and a report judge audits the full provenance graph before a result is accepted.
• Author-reported: Sol27LC lattice constants within about 1% MAPE of expert DFT; CO/Pt(111) FCC-ontop adsorption-energy difference within 2 meV of the expert value. The guarded run uses about 13x the input tokens of the unguarded one.
• Relevant if you build tool-using agents where wrong numbers are costly and you want auditable provenance. Not a general-purpose DFT code.

Problem

Agents running long, multi-step scientific workflows lose context, skip convergence checks, and produce plausible but invalid numbers [Introduction]. Existing provenance tools record what ran but not whether the parameters were valid [Introduction]. Self-consistency voting and self-revision are described as costly or unreliable when the model has no external signal [Introduction].

In periodic DFT, a result can complete without error and still be wrong, for example because the plane-wave cutoff or k-point mesh is not converged [Introduction]. The paper's CO/Pt(111) study shows this: an unconverged slab thickness and vacuum setting still produced a final number close to the expert value, but only 81% of the essential steps succeeded in the unguarded run [Results: Quantitative comparison; tab. 6].

Method

DREAMS has four LLM-driven roles and one shared memory [Results: Multi-agent orchestration; fig. 1]:

1. Planning supervisor. Decomposes the objective into plan steps. Each step records which worker runs it, which tool call must succeed, and, for report steps, which quantities the report has to output. The supervisor edits the plan with insert, modify and delete operations; each edit is validated before it is accepted [Methods: Dynamic planning].
2. DFT worker. Builds structures (AutoCat for adsorption sites, ASE for structures and QE input), selects pseudopotentials, writes the QE input template, generates convergence and equation-of-state (EOS) job series, and extracts results [Methods: DFT LLM agent].
3. HPC worker. Chooses resources, submits SLURM jobs through pysqa, monitors them and retrieves files. It does not change QE's parallelisation [Methods: HPC LLM agent].
4. Convergence agent. An LLM embedded in a tool. It reads a failed job's input, output and error files and suggests parameter changes [Methods: Convergence LLM agent; tab. 3].
5. Canvas. A persistent store for notes (append-only, versioned), artifacts (append-only provenance registry of tool outputs) and reports (immutable after verification). Framework-owned key spaces are read-only for agents [Methods: Memory and communications].

Every guarded tool call follows the sequence below [Methods: Safety guard; fig. 2]. The paper describes the tiers in this order and says a failure at any tier stops the tool from running.

# Guarded tool call  [Methods: Safety guard] [fig. 2]
# Input:  args (values with references), context, per-parameter reasons
# Output: registered artifact, or a rejection with the judge's reasoning

def guarded_call(tool, args, context, reasons):
    # 1. Deterministic check: each referenced source exists in the registry
    #    and the supplied value equals the recorded one  [Methods: Safety guard]
    for ref in args.references:
        check_exists_and_equal(registry, ref)

    # 2. Per-parameter LLM judge: each parameter judged on its own reason
    #    and the declared context  [Results: multi-tier guard; fig. 2]
    for param in args.parameters:
        verdict = judge_parameter(param, reasons[param], context)
        if verdict == "fail":
            return reject(verdict)

    # 3. Cross-parameter LLM judge, only on tools that need it: convergence
    #    selection and EOS fitting  [Methods: Safety guard]
    if tool.needs_cross_parameter_gate:
        verdict = judge_jointly(args, context)
        if verdict == "fail":
            return reject(verdict)

    # 4. Run the tool body and register its output with full provenance
    output = tool.run(args)
    return register(output, tool, args, reasons, context)

The paper states that a warning verdict still registers the value with the concern stamped in its metadata, and that the guard fails open on infrastructure errors [Methods: Safety guard].

After a report is written, a report judge checks each claim against its cited artifact, checks that the artifact is the right kind of source, and walks the provenance graph to judge each parameter of each contributing call [Methods: Safety guard; fig. 5]. The report judge's verdict is the one that decides acceptance; call-time verdicts can differ in ambiguous cases [Methods: Safety guard].

Lattice constant (Sol27LC)

The paper states the DFT workflow in these steps [Results: Sol27LC; fig. 3]:

# Lattice constant from E(V) on a scaled cell  [Results: Sol27LC]
# Input:  element, crystal structure, initial lattice constant a0
# Output: equilibrium lattice constant

def lattice_constant(element, structure, a0):
    # 1. Build the conventional unit cell at a0  [Results: Sol27LC]
    cell = conventional_cell(element, structure, a0)

    # 2. Scale lattice vectors uniformly up to +-5% of a0  [Results: Sol27LC]
    #    The grid below is the repository default  [code: src/tools.py#L628]
    scales = [0.95, 0.975, 1.0, 1.025, 1.05]

    # 3. Converged cutoff and k-point spacing, from the convergence study
    #    [Results: Sol27LC; fig. 4]
    ecut, kspacing = converged_settings(element)

    # 4. Total energy for each scaled cell  [Results: Sol27LC]
    energies = [dft_energy(scale_cell(cell, s), ecut, kspacing)
                for s in scales]

    # 5. Fit an EOS; the minimum gives V0; take the cube root  [Results]
    v0 = fit_eos(volumes(scales, cell), energies).minimum_volume
    return v0 ** (1.0 / 3.0)   # valid only for a cubic conventional cell

Step 5 uses the cube root directly. The paper says the lattice constant is derived from the volume "using the specified crystal symmetry" [Results: Sol27LC]; the code applies no symmetry factor (see Paper vs code).

Convergence selection

The convergence study fixes one parameter and sweeps the other. The paper uses a 0.1 Å⁻¹ k-point spacing for the cutoff sweep and a 120 Ry cutoff for the k-point sweep. The selection threshold is 1 meV/atom [Results: Sol27LC; fig. 4]. The deterministic tool then picks the cheapest tested setting whose energy error stays under the threshold, measured against the most converged run [Results: Sol27LC].

# Convergence selection  [Results: Sol27LC; fig. 4] [code: src/utils.py#L164]
# Input:  energies on a grid of (ecutwfc, kspacing), natoms, threshold
# Output: chosen ecutwfc and kspacing, or "not converged"

def select_settings(grid, natoms, threshold_mev_atom):
    # 1. Sweep the cutoff at the finest kspacing  [code: src/utils.py#L180-L186]
    # 2. Error = |E - E_ref| / natoms, in meV/atom, where E_ref is the
    #    highest-cutoff run  [code: src/utils.py#L184]
    # 3. Take the lowest cutoff with error below the threshold
    #    [code: src/utils.py#L186]
    # 4. Repeat along kspacing at the chosen cutoff
    #    [code: src/utils.py#L195-L197]
    # 5. If the chosen value is the finest tested value, refuse and ask for a
    #    finer sweep  [code: src/tools.py#L1013-L1019]
    return ecut_chosen, kspacing_chosen

Adsorption energy and BEEF ensemble

The adsorption energy is E_slab+ads − (E_slab + E_ads) [Results: CO/Pt(111), eq. 1]. The paper's Methods give the same quantity as E_ads = E_CO-Pt(111) − E_CO − E_Pt(111) [Methods: DFT benchmark, eq. 2]. The reported difference is ΔBE = E_ads_ontop − E_ads_fcc tab. 4.

The uncertainty study uses BEEF-vdW with 2,000 functionals in the ensemble [Methods: DFT benchmark]. Each ensemble is run on a relaxed structure.

Hyperparameters

Results

Author-reported. The paper does not give run-to-run variance beyond the standard deviations in the tables below.

Sol27LC lattice constants tab. 2. Errors are relative to human expert DFT; the paper uses MAPE.

Per-system values are in [SI S-3]. The ranges printed in tab. 2 do not match those per-system values (see Pitfalls).

CO/Pt(111) adsorption-energy difference tab. 4. The paper uses PBE and LDA; the agent and the human expert values are compared against literature ranges.

ΔBE is defined as E_ads_ontop − E_ads_fcc; positive values favour FCC tab. 4.

BEEF-vdW uncertainty fig. 7. Human expert mean −0.13 eV (σ = 0.01 eV); DREAMS mean −0.12 eV (σ = 0.01 eV). Zero lies more than ten standard deviations from the distribution, so FCC is favoured at the GGA level in both [Results: Quantifying uncertainty]. The paper concludes that GGA-level approximations may not fully match experiment [Results: Quantifying uncertainty; Discussion].

Bader charge and C–O bond length tab. 5:

The paper reports 0.15–0.18 e⁻ more transfer to the FCC site than the ontop site [Results: Quantifying uncertainty].

Comparison with other frameworks tab. 6. All four systems share the Sonnet 4.5 backend. Values are averages of at least three runs.

Token totals by category are in tab. 7. DREAMS_safe uses about 13x the input tokens of DREAMS on both challenges and 17x to 32x the output tokens. Judge calls make up about one third of input tokens and four fifths of output tokens on CO/Pt(111) [Results: Quantitative comparison].

Judge models fig. 8. On a 145-scenario adversarial suite, the total errors (false positives plus false negatives) range from 4 to 17 across five Anthropic models. Opus 4.8 (the production judge) has 2 false positives and 5 false negatives. Fable 5 has 1 and 3. Sonnet 4.6 has 10 false positives and 1 false negative. The per-model counts for Sonnet 4.5 and Sonnet 5 are not stated in the text; the figure carries them fig. 8.

Paper vs code

Repository: github.com/BattModels/material_agent, linked from the paper's Code Availability section. Read at commit 99c9d71961df6922bfbca3e3ecdf4afb135a3376. The repository has no LICENSE file. The README does not name a license.

• Lattice constant. Paper: the lattice constant is derived from the volume "using the specified crystal symmetry" [Results: Sol27LC]. Code: returns the cube root of the fitted equilibrium volume with no symmetry factor tools.py. This matches the paper only if the input cell is a cubic conventional cell.
• EOS form. Paper: "a standard equation of state" [Results: Sol27LC]. Code: ASE's EquationOfState class tools.py. The fit form is not named in the paper.
• EOS strain. Paper: up to ±5% with five single-point calculations [Results: Sol27LC]. Code: default scale grid 0.95 to 1.05 in steps of 0.025, step size allowed between 0.01 and 0.1 tools.py. Matches.
• Convergence threshold. Paper: 1 meV/atom [Results: Sol27LC]. Code: default 1.0 meV/atom tools.py. Matches. The select_k_ecut docstring says eV, but the function computes meV/atom utils.py.
• Convergence suggestions. Paper: the convergence agent embeds no parameter-specific heuristics, decision trees or lookup tables [Methods: Convergence LLM agent]. Code: the convergence-diagnosis prompt includes a constraint that the agent must never suggest lowering accuracy, such as loosening the convergence threshold tools.py. This is an instruction the paper's description does not mention.
• Model names. Paper: Sonnet 4.5 for agents, Opus 4.8 for judges [Results: Multi-agent orchestration]. Code: the shipped default config sets ANTHROPIC_MODEL to claude-3-7-sonnet-20250219 default.yaml. The paper's models are not the shipped default.
• BEEF ensemble. Paper: 2,000 functionals [Methods: DFT benchmark]. Code parses an ensemble tag from the QE output and expects 2,000 energies utils.py. Matches.
• Adsorption energy. Code: adsorption energies are fcc minus clean minus CO, and ontop minus clean minus CO tools.py. This uses the same convention as the paper's eq. 2.
• Vacuum default. Paper's final CO/Pt(111) vacuum: 10 Å [Results: CO/Pt(111)]. Code default for adsorbate files: 10 Å tools.py. Matches.
• Judge rules and scenario suite. The paper describes an adversarial scenario harness and rule texts in SI S-11 and S-12 [Methods: Judge implementation]. I did not find the scenario suite or judge rule texts in the cloned tree at this commit. Judge prompts were not compared with the paper's SI text.

The guard tiers, math gate and extraction gate were not compared with code. The cloned tree does not contain a separate guard module that I checked.

Pitfalls

• Lattice constant from volume. The cube root of the EOS volume is the lattice constant only for a cubic conventional cell. The paper says the conventional cell is used [Results: Sol27LC]. A primitive cell passed to the same code would give a wrong value. Check the cell before fitting.
• EOS fit form is unstated. The paper says "standard EOS" and the code uses ASE. An implementer who writes their own fit should expect small differences in V0.
• Threshold reference. The reference for the convergence error is the highest-cutoff or finest-k run in the sweep utils.py. A different reference changes the chosen value. The code refuses to choose when the answer is the finest tested value tools.py. That refusal check is hard-coded to a 120 Ry cutoff and a 0.1 Å⁻¹ spacing, so it does not follow a changed sweep range tools.py.
• Comparability across calculations. The paper says every energy in an adsorption difference must use the same physical settings. Only SCF control parameters may differ, and only when they change convergence rather than the converged energy [Results: Comparability]. The cross-parameter judge enforces this at each selection call.
• Changing the cutoff invalidates dependent tests. When the cutoff changed from 80 Ry to 95 Ry, the paper re-ran the k-point and slab-thickness tests and every calculation in the energy difference [Results: Comparability]. Re-running only the failed step leaves the set inconsistent.
• Provisional values cannot support claims. In the CO/Pt(111) run, an 80 Ry cutoff was used provisionally, and a dotted reference to an input parameter was rejected in production work [Results: CO/Pt(111)]. A value counts as characterized only when a registered output produces it.
• Call-time and report-time verdicts differ. The call-time gate does not walk upstream provenance. In the paper's vacuum case the call-time judge accepted a dotted reference that the report judge rejected [Methods: Safety guard].
• Guards fail open. An infrastructure error in a guard does not block a run. Only a scientific verdict does [Methods: Safety guard]. Monitor guard errors separately.
• Sign convention for ΔBE. tab. 4 defines ΔBE as E_ads_ontop − E_ads_fcc and reports positive values (0.1078 and 0.318 eV), which means FCC is lower. The caption of fig. 7 uses the same definition but reports a mean of −0.13 eV, which would mean ontop is lower. Both cannot hold with one convention. Use the sign that the code produces, checked against the data.
• Table 2 ranges do not match the SI. tab. 2 gives BCC k-point range 8–16 and ecutwfc 40–70. The per-system values in [SI S-3] include k-point 6 (Na) and ecutwfc 30 (Rb), and FCC ecutwfc 30 (Al). The BCC and DIA MAPE values in tab. 2 reproduce from the SI per-system errors; the FCC value recomputes to about 0.52%, not 0.51%.
• Cost. The guarded run uses about 13x the input tokens, and the CO/Pt(111) guarded run totals about 23.9M tokens against 1.8M unguarded tab. 6. The paper says the guard cost grows with workflow activity more than with task complexity [Results: Quantitative comparison].
• Single backend family. The judge panel is Anthropic only. The rules were tuned on CO/Pt(111)-derived scenarios plus one additional chemistry [Methods: Judge implementation]. Generalisation to other domains is not shown.
• Sensitive-parameter list is human-defined. The guard enforces a list written by domain experts. It does not find sensitive parameters itself [Discussion].
• Scope of automation. The paper places the work at L2+ and "approaching L3". The candidate structures, sites and functionals are specified in advance [Discussion]. Do not read the benchmarks as open-ended discovery.
• Figure and table numbers. Figures and tables are numbered in the order they appear in the main text. Supplementary items are cited by their S- heading.

Lineage

• Builds on: MDCrow and ChemGraph are used as baselines in the comparison [Results: Quantitative comparison]. The paper names ReAct and LangGraph as its agent and orchestration frameworks [Methods: Overview].
• Compared against: MDCrow, ChemGraph, and an unguarded DREAMS variant tab. 6.
• Benchmarks: Sol27LC [beef], CO/Pt(111) puzzle [coptpuzzle].
• Superseded by: not stated.