ChemGraph-XANES: An Agentic Framework for XANES Simulation and Analysis

ChemGraph-XANES is an agentic framework that automates and scales X-ray absorption near-edge structure (XANES) simulations by integrating natural language task specification, retrieval-augmented parameter selection, and high-performance parallel execution to streamline complex computational workflows for materials analysis.

The Gist

Imagine you are a chef trying to figure out exactly what's inside a mysterious, complex stew. You can't just taste it; you need to use a special, high-tech scanner (like an X-ray machine) to see the individual ingredients and how they are arranged. In the world of science, this "stew" is a chemical material, and the scanner is a technique called XANES (X-ray Absorption Near-Edge Structure).

For a long time, using this scanner has been like trying to cook a gourmet meal using a recipe written in a foreign language, with instructions scattered across ten different books, and a kitchen where you have to manually turn every single knob yourself. It's powerful, but it's slow, confusing, and prone to mistakes.

Enter ChemGraph-XANES. Think of this as hiring a super-smart, robotic sous-chef who speaks your language, knows the recipe books by heart, and can run the whole kitchen for you.

Here is how it works, broken down into simple concepts:

1. The "Magic Translator" (The Agentic Framework)

Usually, to run these complex simulations, scientists have to write long, boring computer code. With ChemGraph-XANES, you don't need to be a coder. You can just talk to the computer like you're talking to a helpful assistant.

• You say: "Show me what Titanium looks like inside Titanium Dioxide."
• The Robot Agent hears: "Okay, I need to find the structure of Titanium Dioxide, set up the X-ray scanner for the Titanium atom, run the simulation, and show me the results."
• It translates your simple sentence into the complex, technical commands the machine actually needs.

2. The "Library Researcher" (Documentation-Grounded Expert)

One of the hardest parts of science is knowing which settings to use. If you guess wrong, the results are garbage.

• The Problem: The manual for the X-ray scanner (called FDMNES) is huge and technical.
• The Solution: The robot has a "Library Researcher" built into its brain. Before it makes a decision, it instantly flips through the digital manual, finds the exact rule you need, and applies it.
• Why it matters: It stops the robot from "hallucinating" (making things up). It ensures the settings are based on the actual rules of the game, not a guess.

3. The "Assembly Line" (High-Throughput & Parallel Processing)

Imagine you need to scan 1,000 different materials. Doing them one by one would take years.

• The Magic: Because each scan is independent (like baking 1,000 separate cookies), the robot can send them all to a massive "super-kitchen" (a High-Performance Computer) at the same time.
• Instead of one robot baking one cookie at a time, it sends 1,000 robots to bake 1,000 cookies simultaneously. This turns a task that used to take months into one that takes hours.

4. The "Quality Control" (Normalization & Curation)

When you get the results back, they might look messy. Some might be too bright, some too dark, just because of how the machine was set up that day.

• The Robot's Job: It automatically cleans up the data. It adjusts the "volume" and "contrast" of every single result so they can be compared fairly.
• It also keeps a perfect diary (provenance) of exactly which ingredient went into which result, so no one ever loses track of where the data came from.

The Two Ways to Order Your Meal

The paper shows this robot works in two ways:

1. The "Bring Your Own Ingredients" Mode: You give the robot a specific file (like a blueprint of a molecule you built yourself), and it scans that exact thing.
2. The "Order from the Menu" Mode: You just say, "I want to see Iron in Rust." The robot goes out, finds the best blueprint for Rust, picks the Iron part, and runs the scan.

Why This Changes Everything

Before this, only experts who spoke "computer code" and "physics jargon" could use these powerful tools. ChemGraph-XANES opens the door for everyone.

• It makes science faster (thanks to the assembly line).
• It makes science easier (thanks to the translator).
• It makes science more reliable (thanks to the library researcher).

Ultimately, this framework is building a giant, organized library of "chemical fingerprints." Once this library is built, scientists can use it to train Artificial Intelligence to discover new medicines, better batteries, and cleaner fuels much faster than ever before. It's not just about running a simulation; it's about automating the discovery process itself.

Technical Summary

1. Problem Statement

Computational X-ray Absorption Near-Edge Structure (XANES) is a critical tool for probing local coordination, oxidation states, and electronic structures in complex chemical systems. However, the widespread adoption of computational XANES at scale is hindered not by the underlying physics (e.g., the FDMNES simulation method), but by workflow complexity.

• Manual Bottlenecks: Routine large-scale calculations require manual steps: retrieving/constructing structures, identifying absorber sites, specifying parameters, generating code-specific inputs, managing independent runs, extracting spectra, and normalizing data.
• Reproducibility & Scalability Issues: Ad hoc scripts make workflows difficult to reuse, reproduce, or scale.
• High-Throughput Needs: Applications like high-throughput screening, ensemble studies, and machine learning (ML) dataset generation require consistent, automated processing of thousands of spectra, which is currently labor-intensive.
• Input Heterogeneity: Users often start with different input types (e.g., local POSCAR files from DFT vs. chemical formulas for database queries), requiring flexible interfaces that current tools lack.

2. Methodology

The authors present ChemGraph-XANES, an agentic framework built on ASE, FDMNES, Parsl, and LangGraph/LangChain. It unifies natural language (NL) task specification with structured scientific execution.

Core Architecture

• Agentic Orchestration: The framework exposes XANES workflow operations as typed Python tools. Large Language Models (LLMs) act as agents to interpret user requests, select tools, and map NL quantities (e.g., "Ti in TiO2") to structured function arguments.
• Multi-Agent Modes:
  • Single-Agent: Iteratively reasons and invokes tools to complete a task.
  • Multi-Agent: A planner decomposes tasks, worker agents execute them, and an aggregator synthesizes results.
  • Retrieval-Augmented Expert Agent: A specialized agent consults a local knowledge base (derived from the FDMNES manual) to ground parameter selection, reducing hallucinations and ensuring decisions are documentation-based.

Workflow Pipeline

1. Structure Acquisition:
   • Supports file-based inputs (e.g., local .cif, POSCAR) converted to ase.Atoms.
   • Supports database-driven inputs via the Materials Project API, filtering by energy-above-hull and chemical formula.
2. Automatic Input Generation:
   • Converts ase.Atoms objects into FDMNES input files (fdmfile.txt, fdmnes.in.txt).
   • Handles logic for periodic (Crystal mode) vs. non-periodic (Molecule mode) structures.
   • Defaults absorber selection to the highest atomic number element unless specified otherwise.
3. High-Throughput Execution:
   • Uses Parsl for task-parallel execution on High-Performance Computing (HPC) systems.
   • Each structure generates an independent job, allowing massive parallelism.
   • Maintains provenance by linking output spectra back to the source structure (including Materials Project IDs).
4. Post-Processing & Normalization:
   • Parses convolution outputs (*conv.txt).
   • Applies a standardized normalization routine:
     • Estimates edge energy ($E_0$) via numerical derivative or uses a default.
     • Fits linear baselines to pre-edge ($E_0 - 20$ eV) and post-edge ($E_0 + 50$ eV) regions.
     • Normalizes the spectrum relative to the edge step.

3. Key Contributions

• Unified Agentic Interface: Bridges the gap between high-level natural language requests and low-level physics simulations, supporting both explicit file inputs and chemistry-level queries (e.g., "Compute XANES for Ti in TiO2").
• Documentation-Grounded Agents: Introduces a retrieval-augmented mechanism where agents consult the FDMNES manual to determine parameters (e.g., absorber selection, doping keywords), ensuring scientific accuracy and transparency.
• Scalable HPC Integration: Demonstrates a workflow naturally suited for task-parallel execution, enabling the generation of large XANES databases for ML and comparative studies.
• Provenance-Aware Curation: Automatically links spectral data to structural origins and stores results in a serialized database (atoms_db_expanded.pkl) for downstream analysis.

4. Results

The framework was validated through three primary use cases:

1. Documentation-Grounded Parameter Retrieval:
   • The expert agent successfully queried the FDMNES manual to answer questions about default absorber selection, crystal doping, and energy range settings.
   • The agent provided accurate, evidence-based responses, avoiding hallucinations by citing specific manual sections.
2. File-Based Structure Specification:
   • The system successfully processed a local POSCAR file for a MnO2 slab with a Cu absorber ($Z=29$).
   • It correctly bypassed the database retrieval stage, generated inputs, executed the simulation, and produced a normalized spectrum.
3. Natural-Language Chemical System Specification:
   • The system interpreted the query "Compute the XANES for Ti in TiO2."
   • It autonomously queried the Materials Project for TiO2 structures, identified Ti as the absorber ($Z=22$), and executed the full pipeline without explicit file paths provided by the user.

5. Significance

• Democratization of Computational Spectroscopy: By allowing users to interact via natural language, the framework lowers the barrier to entry for complex XANES simulations, making them accessible to non-experts while retaining rigorous scientific logic.
• Reproducibility: The separation of the "orchestration layer" (LLM) from the "scientific backend" (FDMNES/ASE) ensures that the underlying physics remains transparent and reproducible, even as the interface evolves.
• Foundation for AI-Driven Materials Discovery: The ability to generate large, consistent, and normalized XANES databases at scale is a critical enabler for training machine learning models to predict spectroscopic properties or interpret experimental data.
• Future-Proofing: The framework is designed to be extensible; as LLM reliability improves, the range of parameters agents can control can be expanded, provided they remain grounded in documentation and schema validation.

In summary, ChemGraph-XANES represents a significant step toward automated, high-throughput, and accessible computational spectroscopy, effectively solving the workflow bottleneck that has historically limited the scale of XANES studies.