llm-simulation-agent

An LLM agent that drives materials science simulation tools through natural language, built with GPT-4.1, LangChain, and ASE.

What It Does

Ask the agent in plain English and it will call the right simulation tool automatically:

Example query	Tool invoked	Output
"What is the crystal structure of iron?"	get_crystal_structure	BCC, a = 2.87 Angstrom
"Generate a VASP input file for FCC aluminum."	generate_vasp_poscar	POSCAR text
"Create a DAMASK config for BCC iron with C11=231, C12=135, C44=116 GPa."	generate_damask_config	material.yaml
"Plot the Al-Zn binary phase diagram."	generate_phase_diagram	PNG saved to phase_diagram_plots/
"Fetch a TDB file for the Fe-C system."	fetch_tdb_file	TDB file saved to tdb_files/

A carefully engineered system prompt prevents the LLM from fabricating crystal structures, lattice parameters, or elastic constants. Every material property comes from a deterministic code call, not the model's training data.

---

Architecture

User query (plain English)
        |
        v
  GPT-4.1 (temperature=0)
  + anti-hallucination system prompt
        |
        v  (ReAct loop - LangGraph)
  +-------------------------------------+
  |  Tool 1: get_crystal_structure      |  <- ase.data.reference_states
  |  Tool 2: generate_vasp_poscar       |  <- ase.build.bulk() + ase.io.write()
  |  Tool 3: generate_damask_config     |  <- Python dict -> yaml.dump()
  |  Tool 4: generate_phase_diagram     |  <- pycalphad binplot() -> PNG
  |  Tool 5: fetch_tdb_file             |  <- requests -> TDBDB API -> .tdb/.zip
  +-------------------------------------+
        |
        v
  Final answer with file content / plot path

---

Requirements

• Python >= 3.11
• uv package manager
• An OpenAI API key

---

Installation

git clone https://github.com/YOUR_USERNAME/llm-simulation-agent.git
cd llm-simulation-agent
uv sync

Add your API key to the .env file:

OPENAI_API_KEY=sk-proj-your-key-here

---

Usage

uv run jupyter notebook

Open llm_simulation_agent.ipynb and run all cells in order.

Register as a permanent Jupyter kernel (optional)

uv run python -m ipykernel install --user \
    --name llm-simulation-agent \
    --display-name "llm-simulation-agent"

---

Tool Reference

get_crystal_structure(element: str) -> str

Wraps ase.data.reference_states to return the ground-state symmetry and lattice constant for any element in the periodic table.

Input : "Fe"
Output: Element: Fe | Atomic number: 26 | Crystal structure: bcc | Lattice const. a: 2.87 Angstrom

generate_vasp_poscar(element: str, crystal_structure: str) -> str

Builds a conventional unit cell with ase.build.bulk() and serialises it to VASP5 POSCAR format via ase.io.write(..., format='vasp').

Input : element="Al", crystal_structure="fcc"
Output: POSCAR for Al (FCC) - 4-atom conventional cell

generate_damask_config(phase_name, C11_GPa, C12_GPa, C44_GPa) -> str

Converts GPa elastic constants to SI (Pa) and emits the phase block of a DAMASK 3 material.yaml. Checks Born stability criteria and computes the Zener anisotropy ratio A = 2*C44 / (C11 - C12).

Input : phase_name="BCC_Iron", C11_GPa=231, C12_GPa=135, C44_GPa=116
Output: DAMASK material.yaml (phase block, SI units)

generate_phase_diagram(element1, element2, temp_min, temp_max, tdb_filename) -> str

Computes and plots an isobaric binary phase diagram using pycalphad. Reads a TDB (thermodynamic database) file from the tdb_files/ directory — auto-detected by element name — and saves the result as a PNG in phase_diagram_plots/.

Input : element1="Al", element2="Zn", temp_min=300, temp_max=1500
Output: PNG saved to phase_diagram_plots/AL-ZN_phase_diagram.png

fetch_tdb_file(element1: str, element2: str) -> str

Queries the TDBDB database (Brown University) to find and download a TDB thermodynamic file for a binary system. Handles both direct .tdb downloads and .zip archives transparently, saving the file to tdb_files/ for immediate use by generate_phase_diagram.

Input : element1="Al", element2="Zn"
Output: tdb_files/AL-ZN_Cui_et_al._(2010).tdb  (downloaded automatically)

---

Prompt Engineering: Preventing Hallucination

Section 9 of the notebook compares:

• Controlled agent (with system prompt): refuses to invent elastic constants, correctly errors on fictional materials like "Mithril", and fetches TDB files automatically before attempting phase diagram generation
• Unconstrained agent (no system prompt): may answer from memorised training data

Key rules enforced via system prompt:

ALWAYS call the appropriate tool; never answer from memory alone.
NEVER invent or guess crystal structures, lattice parameters, or elastic constants.
If the user has not supplied elastic constants, ask for them.
If a tool returns an error, relay the exact error message.
For phase diagrams: call fetch_tdb_file first if no TDB file is present locally.

---

Project Structure

llm-simulation-agent/
    llm_simulation_agent.ipynb  - Main notebook
    pyproject.toml              - uv project manifest and dependencies
    uv.lock                     - Pinned dependency lockfile
    .env                        - API key (not committed to git)
    tdb_files/                  - TDB thermodynamic database files (auto-populated)
    phase_diagram_plots/        - Output PNG phase diagrams
    README.md

---

Dependencies

Package	Role
langchain + langchain-openai	LLM interface and @tool decorator
langgraph	ReAct agent loop via create_react_agent
ase	Crystal structure data, bulk builder, VASP I/O
pyyaml	DAMASK material.yaml serialisation
pycalphad	CALPHAD-based binary phase diagram computation
matplotlib	Phase diagram plotting and PNG export
requests	TDB file download from TDBDB API
python-dotenv	Loads API key from .env file
jupyter / notebook	Interactive notebook environment

---

License

MIT