ChemGraph Agent Guide

Overview

ChemGraph is an agentic framework from Argonne National Lab that automates molecular simulation workflows using LLMs. Built on LangGraph and ASE (Atomic Simulation Environment), it enables natural language control of computational chemistry tasks — structure generation, geometry optimization, thermochemistry, and more. Supports DFT (NWChem, ORCA), semi-empirical (xTB), and ML potentials (MACE).

Installation

pip install chemgraph

# Or via Docker
docker pull ghcr.io/argonne-lcf/chemgraph:latest

Core Capabilities

Natural Language Chemistry

from chemgraph import ChemGraphAgent

agent = ChemGraphAgent(
    llm_provider="anthropic",
    calculator="xtb",  # fast semi-empirical
)

# Natural language molecular tasks
result = agent.run("Optimize the geometry of caffeine and calculate its vibrational frequencies")
print(result.energy)
print(result.frequencies)

# Thermochemistry
result = agent.run("Calculate the enthalpy of formation of ethanol at 298K")
print(f"ΔHf = {result.enthalpy:.2f} kJ/mol")

Supported Calculators

Calculator	Type	Speed	Accuracy
xTB (TBLite)	Semi-empirical	Fast	Moderate
MACE	ML potential	Fast	Good
NWChem	Ab initio DFT	Slow	High
ORCA	Ab initio/DFT	Slow	High
UMA	Universal ML	Fast	Good

Workflow Automation

# Multi-step workflow
workflow = agent.create_workflow([
    "Generate 3D structure of aspirin from SMILES",
    "Optimize geometry with DFT/B3LYP/6-31G*",
    "Calculate IR spectrum",
    "Identify key functional group vibrations",
])
results = workflow.execute()

# Reaction pathway
pathway = agent.run(
    "Find the transition state for the Diels-Alder reaction "
    "between butadiene and ethylene"
)