{"id":50464341,"url":"https://github.com/siyu-hu/relaxdiff","last_synced_at":"2026-06-01T06:30:38.134Z","repository":{"id":359157168,"uuid":"1244476821","full_name":"siyu-hu/relaxdiff","owner":"siyu-hu","description":"Diff two crystal structures, surface every change (displacement, bonds, coordination, cell, symmetry), and read an LLM narrative explaining whether the DFT relaxation looks reasonable. CIF / POSCAR / extxyz.","archived":false,"fork":false,"pushed_at":"2026-05-20T16:04:35.000Z","size":1286,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T21:39:12.958Z","etag":null,"topics":["3dmol","ase","computational-materials-science","crystal-structure","dft","llm","materials-informatics","materials-science","pymatgen","quantum-espresso","relaxation","spglib","structure-comparison","structure-diff","vasp"],"latest_commit_sha":null,"homepage":"https://siyu-hu.github.io/relaxdiff/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/siyu-hu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T09:52:28.000Z","updated_at":"2026-05-20T16:04:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/siyu-hu/relaxdiff","commit_stats":null,"previous_names":["siyu-hu/relaxdiff"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/siyu-hu/relaxdiff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siyu-hu%2Frelaxdiff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siyu-hu%2Frelaxdiff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siyu-hu%2Frelaxdiff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siyu-hu%2Frelaxdiff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siyu-hu","download_url":"https://codeload.github.com/siyu-hu/relaxdiff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siyu-hu%2Frelaxdiff/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33763647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3dmol","ase","computational-materials-science","crystal-structure","dft","llm","materials-informatics","materials-science","pymatgen","quantum-espresso","relaxation","spglib","structure-comparison","structure-diff","vasp"],"created_at":"2026-06-01T06:30:37.270Z","updated_at":"2026-06-01T06:30:38.126Z","avatar_url":"https://github.com/siyu-hu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/banner.svg\" alt=\"RelaxDiff — drop in two structures, get a relax sanity check\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A diagnostic viewer for \u003cb\u003eDFT geometry-relaxation\u003c/b\u003e output \u0026mdash;\n  diff two crystal structures, surface every meaningful change\n  (atomic displacement, bond \u0026amp; coordination shifts, cell strain,\n  symmetry breaking) and read a one-paragraph LLM narrative that explains\n  whether the relaxation looks reasonable.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://siyu-hu.github.io/relaxdiff/\"\u003e\u003cb\u003eLive demo\u003c/b\u003e\u003c/a\u003e ·\n  \u003ca href=\"#quick-start\"\u003eQuick start\u003c/a\u003e ·\n  \u003ca href=\"#showcase\"\u003eShowcase\u003c/a\u003e ·\n  \u003ca href=\"#how-it-works\"\u003eHow it works\u003c/a\u003e ·\n  \u003ca href=\"LICENSE\"\u003eMIT License\u003c/a\u003e\n\u003c/p\u003e\n\n## Quick start\n\n```bash\ngit clone https://github.com/siyu-hu/relaxdiff \u0026\u0026 cd relaxdiff\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e .\nrelaxdiff before.cif after.cif -o report.html\nopen report.html        # macOS — use xdg-open on Linux\n```\n\nDon't want to install anything locally? Spin up a preconfigured Codespace in your browser:\n\n\u003cp\u003e\n  \u003ca href=\"https://codespaces.new/siyu-hu/relaxdiff?quickstart=1\"\u003e\n    \u003cimg src=\"https://github.com/codespaces/badge.svg\" alt=\"Open in GitHub Codespaces\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThe Codespace auto-runs `pip install -e .` on first boot, so once it's ready you can run the CLI directly in the integrated terminal.\n\n---\n\n\u003e **Built for:** VASP, Quantum ESPRESSO, ABINIT, CP2K, ASE, pymatgen, MACE / CHGNet relaxations — anything that writes a CIF / POSCAR / extxyz before-and-after pair.\n\nMost crystal structure viewers let you **see** a relaxation. RelaxDiff tells you **whether it looks reasonable**.\n\nIt diffs two structures along every axis a researcher cares about \u0026mdash; per-atom displacement, bond breaking / forming, coordination changes, cell strain, space group changes \u0026mdash; and produces a self-contained HTML report with a 3D viewer, severity-tagged findings, and a short natural-language narrative. One command. No server. No toolchain.\n\n```bash\nrelaxdiff before.cif after.cif -o report.html\n```\n\n**Supported input formats:** CIF · POSCAR / CONTCAR / `.vasp` · `.xyz` / `.extxyz` · pymatgen JSON · ASE `Atoms` (when used as a library). Both structures must share composition and atom count.\n\n## What you get\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cb\u003eInteractive 3D diff viewer\u003c/b\u003e\u003cbr/\u003e\n      Toggle Before / After / Overlay / Diff heatmap. In \u003ci\u003eDiff heatmap\u003c/i\u003e mode every atom is colored by how far it moved \u0026mdash; small movement blue, big movement red \u0026mdash; so problem atoms jump out at a glance.\u003cbr/\u003e\u003cbr/\u003e\n      \u003cimg src=\"docs/assets/screenshot-diff-heatmap.png\" alt=\"Diff heatmap mode\" width=\"100%\"/\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003cb\u003eSeverity-tagged diagnosis\u003c/b\u003e\u003cbr/\u003e\n      Eleven rules turn raw geometry into severity-tagged findings: large displacement, runaway atoms, cell collapse, bond breaking, coordination changes, broken or elevated symmetry, large shear. Every report gets an overall OK / INFO / WARN / ALERT chip.\u003cbr/\u003e\u003cbr/\u003e\n      \u003cimg src=\"docs/assets/screenshot-collapse.png\" alt=\"Alert-level report\" width=\"100%\"/\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003cb\u003eLLM narrative (optional)\u003c/b\u003e\u003cbr/\u003e\n      Reads the structured diagnosis JSON \u0026mdash; never raw coordinates \u0026mdash; and produces a three-paragraph plain-English read of the result, citing specific atom indices. Works with any OpenAI-compatible LLM endpoint (see \u003ca href=\"#llm-narrative\"\u003ebelow\u003c/a\u003e). Without an API key, a deterministic template covers the same ground.\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cb\u003eAdaptive symmetry detection\u003c/b\u003e\u003cbr/\u003e\n      Runs a tolerance scan with \u003ccode\u003espglib\u003c/code\u003e and picks an effective \u003ccode\u003esymprec\u003c/code\u003e automatically, so a small rattle doesn't get misread as full P1 collapse but a real distortion still trips the rule.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Showcase\n\nFour predefined cases, auto-built and deployed to the gallery:\n\n| Case | Severity | What it shows |\n|---|---|---|\n| [MgO normal relax](https://siyu-hu.github.io/relaxdiff/cases/mgo_normal.html) | ![](https://img.shields.io/badge/-OK-1a7f37?style=flat-square) | Clean baseline \u0026mdash; what an unremarkable relaxation looks like |\n| [SrTiO₃ octahedral tilting](https://siyu-hu.github.io/relaxdiff/cases/srtio3_tilting.html) | ![](https://img.shields.io/badge/-WARN-9a6700?style=flat-square) | Cubic → tetragonal-tilted variant; symmetry breaking + coordination shifts |\n| [Si cell collapse](https://siyu-hu.github.io/relaxdiff/cases/collapse.html) | ![](https://img.shields.io/badge/-ALERT-cf222e?style=flat-square) | Cell pressed to ~78% of original volume; full symmetry loss |\n| [TiO₂ strained variant](https://siyu-hu.github.io/relaxdiff/cases/tio2_phase.html) | ![](https://img.shields.io/badge/-WARN-9a6700?style=flat-square) | Large shear + heavy rattle; broken bonds + coordination changes |\n\nRebuild them locally in seconds (no DFT, no ML potential \u0026mdash; just geometric construction):\n\n```bash\npython examples/build.py\n```\n\n## Install\n\n```bash\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e .\n```\n\n## Use\n\n```bash\nrelaxdiff before.cif after.cif -o report.html\n```\n\nOpen `report.html` in any browser. Self-contained, no server required.\n\n### Options\n\n```\n--title TEXT             Report title shown in the header\n--no-llm                 Skip the LLM narrative, use the deterministic template\n--json PATH              Also dump structured diagnosis as JSON\n--threshold-displacement Override the default 0.5 Å warn threshold (Å)\n```\n\n### LLM narrative\n\nRelaxDiff talks to **any OpenAI-compatible chat-completions endpoint** \u0026mdash; OpenAI, DeepSeek, Together, Groq, Fireworks, Ollama, your own vLLM server, etc.\n\n```bash\ncp .env.example .env\n# edit .env with your LLM provider's API key, model, and base URL\nexport $(grep -v '^#' .env | xargs)\nrelaxdiff before.cif after.cif -o report.html\n```\n\nWithout `RELAXDIFF_LLM_API_KEY` (or with `--no-llm`), the report falls back to a deterministic three-paragraph template. No internet required.\n\n| Provider | `RELAXDIFF_LLM_MODEL` | `RELAXDIFF_LLM_BASE_URL` |\n|---|---|---|\n| DeepSeek | `deepseek-chat` | `https://api.deepseek.com` |\n| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` |\n| Together | e.g. `meta-llama/Llama-3-8b-chat-hf` | `https://api.together.xyz/v1` |\n| Groq | e.g. `llama-3.1-70b-versatile` | `https://api.groq.com/openai/v1` |\n| Ollama (local) | e.g. `llama3` | `http://localhost:11434/v1` |\n\n### CI / Secrets\n\nCI auto-rebuilds and deploys the gallery on every push to `main`. It uses the deterministic narrative by default \u0026mdash; no API calls, no token cost.\n\nTo regenerate narratives with an LLM from CI:\n\n1. Repo → **Settings** → **Secrets and variables** → **Actions** → add a repo secret named `RELAXDIFF_LLM_API_KEY`. Optionally add `RELAXDIFF_LLM_MODEL` and `RELAXDIFF_LLM_BASE_URL` as variables (not secrets).\n2. Repo → **Actions** → *Deploy demo site to GitHub Pages* → **Run workflow** → tick `use_llm`.\n\n`.env` is gitignored. CI only sees the secret on the manual `use_llm=true` path. Nothing in this repo ever stores a key in plain text.\n\n## How it works\n\n```\ntwo structures\n   ↓ pymatgen StructureMatcher (Hungarian fallback)   site-by-site mapping\n   ↓ geometry + symmetry analysis                     deterministic\n   ↓ 11 rules + adaptive symprec                      severity-tagged findings\n   ↓ OpenAI-compatible LLM (or fallback template)     3-paragraph narrative\n   ↓ Jinja2 + 3Dmol.js                                self-contained HTML\nreport.html\n```\n\nThe LLM is the **last** thing in the pipeline and only ever sees structured JSON \u0026mdash; atom indices, magnitudes, rule outputs \u0026mdash; not raw coordinates. Hallucination surface stays small. See [PLAN.md](PLAN.md) for the full design.\n\n## What it is not\n\n- Not a general structure viewer (use [matterviz](https://github.com/janosh/matterviz))\n- Not an MD defect analyzer (use [OVITO](https://www.ovito.org))\n- Not a VESTA plugin (VESTA has no plugin API)\n- Not a real-time interactive editor\n\n## Keywords\n\nDFT relaxation · ionic relaxation diagnostics · crystal structure diff · before/after relaxation comparison · VASP / Quantum ESPRESSO / ABINIT / CP2K post-processing · pymatgen + ASE · spglib symmetry analysis · materials informatics · interactive 3D structure viewer · LLM for materials science\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiyu-hu%2Frelaxdiff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiyu-hu%2Frelaxdiff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiyu-hu%2Frelaxdiff/lists"}