hello-qm/catgo-lrg/analysis

Analysis Router

This skill routes analysis requests to the correct sub-skill based on what the user is asking for.

Routing Table

MCP Tool: catgo_analyze

All analysis actions use the catgo_analyze tool with an action parameter.

{"tool": "catgo_analyze", "arguments": {"action": "convergence", ...}}
{"tool": "catgo_analyze", "arguments": {"action": "frequencies", ...}}
{"tool": "catgo_analyze", "arguments": {"action": "forces", ...}}

MCP Tool: catgo_workflow_engine

Most analysis workflows are built as DAGs using the workflow tool.

{"tool": "catgo_workflow_engine", "arguments": {"action": "create", "name": "Analysis WF"}}
{"tool": "catgo_workflow_engine", "arguments": {"action": "add_task", "workflow_id": "...", "task_type": "gibbs_energy", ...}}

Python API Pattern

All analysis workflows follow the same skeleton:

from catgo.workflow import Workflow
wf = Workflow("Analysis name")
# 1. Input structure
inp = wf.add_task("structure_input", structure=structure_json)
# 2. Compute (geo_opt, single_point, freq, etc.)
opt = wf.add_task("geo_opt", structure=inp.output.structure, software="vasp")
frq = wf.add_task("freq", structure=opt.output.structure, software="vasp",
                   freeze_mode="layers", freeze_layers=4)
# 3. Analyze (gibbs_energy, dos_analysis, charge_analysis, etc.)
gib = wf.add_task("gibbs_energy", energy=opt.output.energy,
                   frequencies=frq.output.frequencies, phase="adsorbed")
wf.submit()

Decision Guide

• Single intermediate (H*, OH) --> her/, adsorption/
• Multiple intermediates in reaction pathway --> oer/, co2rr/
• Parameter sweep, no reaction --> convergence/
• Post-processing existing calculation --> dos_analysis/, charge/
• Converting DFT energy to thermodynamic quantity --> gibbs/

Common Pitfalls

1. Always run geo_opt before freq -- frequencies on unrelaxed structures are meaningless.
2. For surface calculations, always use freeze_mode="layers" in freq to avoid

imaginary frequencies from slab bottom atoms.

1. Gibbs energy needs both energy (from geo_opt) and frequencies (from freq) --

these come from separate tasks connected via output references.

1. Convergence tests use single_point (not geo_opt) to isolate the parameter effect.