lamm-mit/dreams

dreams

Agentic materials discovery and DFT simulation framework using ASE, Quantum ESPRESSO, and Claude LLMs via LangGraph.

Code repository

https://github.com/BattModels/material_agent

Use this as the implementation source: clone the repo and follow its README for install, dependencies, and how to run code or experiments. The generated client prints JSON with a suggested git clone command.

Paper (arXiv — explanation)

https://arxiv.org/abs/2507.14267

This is the paper reference. The client can optionally fetch live Atom metadata (title, abstract) for agents; it does not run training or upstream research code by itself.

What “running” this client does

The *_client.py script prints JSON that combines a GitHub repository (clone URL + suggested git clone) with optional paper context from arXiv (live Atom metadata when reference_url is arXiv). Run the real code by cloning the repo and following its README — the skill is your agent-facing entrypoint, not a substitute for the repo’s install steps.

To call a REST API instead, set BASE_URL in scripts/dreams_client.py or wrap the upstream CLI with subprocess after clone.

How to run the method (from the source)

Extracted for operators and agents. Confirm against the upstream repository or paper before relying on it in production.

Prerequisites

• Quantum ESPRESSO installed and available in system PATH
• Anthropic API key (or alternative LLM provider packages installed)
• Conda package manager
• ASE (Atomic Simulation Environment) and LangGraph compatible Python environment

Installation

1. Clone the repository:

   git clone https://github.com/BattModels/material_agent.git
   cd material_agent
   

2. Create and activate conda environment:

   conda env create -f environment.yml
   conda activate dreams
   

   Note: Environment setup typically takes 5–10 minutes. Default setup supports Anthropic models only.

3. Install Quantum ESPRESSO:

   • Follow official QE installation: https://www.quantum-espresso.org/
   • Ensure pw.x and related executables are in system PATH or modify QE_submission_example in prompt.py

4. Configure API keys and paths:

   • Edit config/default.yaml:
     • Add your Anthropic (or alternative LLM provider) API key
     • Specify pseudopotential directory and paths
     • Set working directory for DFT calculations

How to run

1. Edit the task specification in invoke.py:

   # Example: Calculate lattice constant for BCC Li
   usermessage = "You are going to calculate the lattice constant for BCC Li through DFT, the experiment value is 3.451, use this to create the initial structure."
   

2. Run the agent:

   python invoke.py
   

The agent will autonomously:

• Parse the task via Claude LLM
• Generate initial atomic structures
• Configure and submit DFT calculations to Quantum ESPRESSO via ASE
• Analyze results and iterate if needed
• Return final materials property predictions

Configuration

Environment Variables & Config File (config/default.yaml):

• ANTHROPIC_API_KEY: Required for Claude model access
• pseudopotentials_dir: Path to pseudo-potential files (e.g., PAW datasets)
• working_directory: Directory for DFT calculations and outputs
• qe_path: Path to Quantum ESPRESSO executables (if not in PATH)
• exchange_correlation_functional: XC functional choice (e.g., PBE)

For non-Anthropic LLMs:

• Install provider-specific packages
• Modify planNexe2.py and tools.py to integrate alternative LLM APIs

Demo Video: Full walkthrough available at Google Drive demo

The same text lives in scripts/USAGE.md for tools that prefer reading files under scripts/.

Parameters

--api-key (str) [required] API key for authentication --task-description (str) [required] Natural language task specification for the materials simulation (e.g., lattice constant calculation, adsorption energy prediction). Defined in invoke.py usermessage. --config-file (str) [optional, default=config/default.yaml] Path to YAML configuration file containing API keys, pseudopotentials, and working directory.

Usage

python3 scripts/dreams_client.py python invoke.py

Example Output

{"calculation_result": "lattice_constant_value", "dft_converged": true, "explanation": "..." }