CompCalc Assistant

A local RAG (Retrieval-Augmented Generation) assistant for generating, validating, and troubleshooting inputs and outputs of computational materials-science codes — Quantum ESPRESSO, BerkeleyGW, and LAMMPS. It is grounded in your own calculation history plus the official documentation, runs locally on Ollama by default, and can switch to the Claude API when you want higher-quality answers.

---

Why

Setting up these calculations means tracking down the right flags, cutoffs, pseudopotentials, and convergence parameters across thousands of lines of documentation and dozens of old run folders. This tool turns that institutional knowledge — including your past inputs — into something you can just ask:

"Write a pw.x SCF input for monolayer MoS2 with PBE, 6x6x1 k-grid, SOC, 60 Ry cutoff, similar to my previous MoS2 calculations."

And, on the output side:

"Did this scf.out converge? If not, what should I change?"

---

Two capabilities

1. Input generation & consistency — Phase 1 (working)

• Generate pw.x / ph.x, epsilon.inp / sigma.inp / kernel.inp / absorption.inp, and LAMMPS scripts that follow your conventions.
• Keep workflows consistent: matching cutoffs, k/q-grids, and file linking across steps.
• Retrieve facts from your own runs ("what epsilon cutoff did I use for WSe2?").

2. Output analysis — Phase 2 (scaffolded; see roadmap)

Parsers under compcalc/parsers/ (wired to scripts/analyze.py) will:

• Extract data — total energies, forces, stresses, Fermi levels (QE); QP corrections and exciton energies (BerkeleyGW); thermo tables and trajectories (LAMMPS).
• Check success — detect JOB DONE, normal termination, completed timesteps; flag non-convergence, crashes, lost atoms, wall-time kills, file/grid mismatches.
• Propose corrections — map known failure signatures to remedies (e.g. raise electron_maxstep, lower mixing_beta, add smearing for metals, fix pair_coeff ordering), optionally routed through the RAG engine for context-aware suggestions.
• Where possible these reuse ASE (ase.io.read) instead of reimplementing parsers; custom logic is reserved for convergence/error states and for BerkeleyGW.

---

Architecture

data/docs (manuals)   data/inputs (your past .in/.inp)   data/notes   extra_dirs (QE docs)
        \                      |                            /            /
         +----------------- SimpleDirectoryReader ---------+------------+
                                   |
                          Chroma vector index  <--  Ollama embeddings (nomic-embed-text)
                                   |
                   code-aware query engine (qe / bgw / lammps prompts)
                                   |
                    LLM backend:  Ollama (local)  OR  Claude API
                                   |
                              CLI  (scripts/)

Component	Choice
RAG framework	LlamaIndex
LLM backend	Pluggable — Ollama (default) or Anthropic Claude API
Embeddings	Ollama nomic-embed-text (no torch/HF download)
Vector store	ChromaDB (persistent)
Interface	CLI (ingest.py, query.py, analyze.py)

---

Storage layout (this machine)

The project lives on the internal disk:

~/assistent_LLM/
├── env/                  # conda environment (all Python deps)
└── compcalc-assistant/   # this repo + index_store/ + data/

Ollama models use the default ~/.ollama/models location (internal). ~4 GB total footprint (≈3 GB models + ≈0.9 GB env). No external drive required.

---

Setup

Already provisioned on this machine. To reproduce elsewhere:

# 1. Environment
conda create --prefix ~/assistent_LLM/env python=3.11 -y
conda activate ~/assistent_LLM/env
pip install -r requirements.txt

# 2. Ollama + models
brew install --cask ollama-app   # the Homebrew *formula* lacks the inference binary
ollama serve &                   # leave running
ollama pull nomic-embed-text
ollama pull llama3.2             # or qwen2.5-coder for stronger input generation

Day to day:

source activate.sh             # activates the conda env
ollama serve &                 # if not already running

---

Usage

# Build / refresh the index (run after adding data or docs)
python scripts/ingest.py

# Generate an input
python scripts/query.py "Write a pw.x SCF input for monolayer MoS2, PBE, 60 Ry cutoff"

# Force a code context and show the sources used
python scripts/query.py --code bgw --sources "Generate a sigma.inp for a TMD monolayer"

# Analyze an output  (Phase 2 — scaffolded)
python scripts/analyze.py scf.out

Python API:

from compcalc import CompCalcEngine
engine = CompCalcEngine.load()
print(engine.query("What epsilon cutoff did I use for my WSe2 GW calculations?"))

Switching to the Claude API

In config.yaml (or a gitignored config.local.yaml):

llm:
  backend: anthropic
  anthropic:
    model: claude-sonnet-4-6

then export ANTHROPIC_API_KEY=... and run as usual.

---

Configuration

config.yaml controls the backend, models, data directories, ingestion excludes, and the index location. Paths are resolved relative to the repo root. Put machine-specific overrides and secrets in config.local.yaml (gitignored).

---

Adding your data

Drop files into data/{docs,inputs,notes}/{qe,bgw,lammps}/ and re-run ingest.py. The whole data/ tree and the vector index are gitignored — your calculations and notes stay private; only code is ever published.

---

Roadmap

• Phase 1: ingest + code-aware query (QE, BGW, LAMMPS)
• Phase 1: pluggable Ollama / Claude backend
• Phase 2: output parsing — data extraction, success checks, fix suggestions
• Phase 2: input validation (flag existence, unit sanity, grid consistency)
• Phase 2: convergence tracking across runs
• Phase 3: EPW & Wannier90 support
• Phase 3: HPC job-script generation (SLURM: Perlmutter / Pinnacles)
• Phase 3: optional Jupyter widget interface