CatAgent skill

CatAgent turns one plain-language question ("CO adsorption energy on Pt(111) by site") into a relaxed slab + adsorbate calculation with a machine-learned interatomic potential (MLIP) and returns numbers, a plot and a rendered structure. Web UI: https://catagent.schoung.com. Source of this skill: https://github.com/s-choung/Research-Skills/tree/master/skills/catagent.

Use it when the user wants demo-grade (fmax 0.1 eV/A, 60 steps, 36-atom slab) adsorption energies in about 1 to 4 minutes, not publication-grade DFT.

0. Decide the mode

Both modes use the same harness API (section 3), so a script written for one runs in the other.

1. Remote mode: HTTP API

Base URL https://catagent.schoung.com. All bodies are JSON. Long stages return {"jobId": ...} immediately; poll GET /api/simjob?id=<jobId> every 5 s until status == "done", then read .result.

1.1 Plan (LLM, ~5 s)

curl -s https://catagent.schoung.com/api/plan \
  -H 'content-type: application/json' \
  -d '{"message": "Pt(111)에서 CO 흡착 에너지를 ontop, bridge, fcc, hcp site별로 비교해줘.", "model": "openai/gpt-6-luna"}'

Response: {"parsed": {"status": "spec"|"need_clarification", "tags": {...}, "spec": {...}}, "raw": "...", "usage": {...}}. If status is need_clarification, ask the user the listed questions and call /api/plan again with the answer appended to the message. Keep the whole spec object; every later stage takes it.

1.2 Write the script (LLM, ~15 s)

curl -s https://catagent.schoung.com/api/codewrite \
  -H 'content-type: application/json' \
  -d '{"spec": <spec>, "mlip": "mace-small", "query": "<original question>", "model": "openai/gpt-6-luna"}'
# -> {"jobId": "job_..."}   then poll /api/simjob?id=job_...

result.code is a python script that only imports from catagent_harness. mlip is one of mace-small (default, fastest), mace-medium, uma-s. You may also write the script yourself with section 3 and skip this call.

1.3 Static audit (LLM, ~3 s, optional but recommended)

curl -s https://catagent.schoung.com/api/audit -H 'content-type: application/json' \
  -d '{"spec": <spec>, "code": "<script>"}'
# poll -> result: {"verdict": "pass"|"fix", "issues": [...], "fix_instruction": "..."}

On fix, call /api/codewrite again with fixInstruction and prevCode.

1.4 Structure preview (no MLIP, ~20 s, optional)

curl -s https://catagent.schoung.com/api/preview -H 'content-type: application/json' \
  -d '{"code": "<script>", "mlip": "mace-small"}'
# -> {"runId": "run_...", "slabs": ["/live/run_.../preview_slab_0.png", ...], "adsAll": [...]}

Show the PNG urls to the user before spending compute. Pass runId as previewRunId in the next call so the files land in the same run folder.

1.5 Simulate (MLIP on ccel-mace, 1 to 4 min)

curl -s https://catagent.schoung.com/api/simulate -H 'content-type: application/json' \
  -d '{"code": "<script>", "mlip": "mace-small", "taskId": "co_pt111", "previewRunId": "run_..."}'
# -> {"jobId": "job_..."}
curl -s 'https://catagent.schoung.com/api/simjob?id=job_...'
# running: {"status": "running", "queueAhead": 0, "initialRender": "/live/run_.../initial.png"}
# done:    {"status": "done", "result": {"exit": 0, "output": "<stdout>", "runId": "run_...",
#           "render": "/live/run_.../structure.png", "walltime_s": 41.2, "hardware": "ccel-mace (16-core CPU)"}}

Tell the user the expected time before starting: spec.estimated_runtime_s from the planner, or 4 s per relax with MACE-small (15 s with UMA), two relaxes per case. exit != 0 means a python error; the traceback is in output. Fix the script (or call /api/codewrite with fixInstruction set to the traceback) and resubmit. Do not resubmit unchanged code.

1.6 Read the numbers

The script prints one line RESULT_JSON:{...} with every requested value in eV, plus CASE <label> E_ads_eV=<v> converged=<bool> lines and [harness] E_ads(...) lines with fmax_final. Parse RESULT_JSON from output yourself, or ask the analyzer:

curl -s https://catagent.schoung.com/api/analyze -H 'content-type: application/json' \
  -d '{"query": "<question>", "spec": <spec>, "stdout": "<output>", "lang": "en"}'
# poll -> result: {"verdict": "success"|"expert_review"|"failed", "conclusion": "...",
#                  "key_numbers": {...}, "physical_check": "..."}

Optional plot: POST /api/resultplot with {"query", "spec", "runId"} returns /live/<runId>/result_plot.png. Files under /live/<runId>/ (structure.png, structure.extxyz, results.json, result_plot.png) are fetchable with plain GET.

1.7 Etiquette

• One simulation at a time per visitor. If queueAhead > 0, wait, do not resubmit.
• Do not loop over dozens of surfaces from a script. Six cases per query is the practical limit (about 3 minutes).
• No NEB, no molecular dynamics, no cells beyond 4x4x4, no steps > 80. The static auditor rejects these.
• Report every energy with its sign convention and fmax_final. Demo-grade means fmax 0.1 eV/A on a 36-atom slab.

2. Local mode

pip install ase mace-torch          # or: pip install fairchem-core for UMA
cp skills/catagent/catagent_harness.py ./
python my_script.py                 # my_script.py imports from catagent_harness

catagent_harness.py in this folder is the server copy with the MLIP fixed to mace-small. Edit the _MLIP_KEY line at the top to mace-medium or uma-s. Set CATAGENT_PREVIEW=1 in the environment to run with a null calculator (structure check only, no MLIP download).

3. Harness API (the only imports a script may use)

from catagent_harness import (
    build_slab, build_alloy_slab, build_hea_slab, build_rutile_slab,
    ontop_sites, cus_sites, bridge_o_sites, surface_symbols,
    adsorption_energy, site_scan, ontop_scan,
    gas_energy, reference_energy, free_energy_correction,
    sabatier_activity, reaction_energy, relax, save_structure,
)

Allowed extra imports: json, math, numpy, itertools, collections. Never build a calculator, never call ase.io.write, never use os/sys/subprocess/pickle.

Builders

Sites

"ontop" | "bridge" | "fcc" | "hcp" (pure metal, first surface cell), "ontop:<atom index>" (any top-layer atom; use ontop_sites(slab) to list them), "cus" / "cus:<k>" and "bridge_O" / "bridge_O:<k>" (rutile), or an (x, y) tuple in Angstrom. On alloys and HEAs bare "ontop" resolves to the host-element top atom nearest the cell centre. On stepped facets (211) bare "ontop" also resolves to a top-layer atom; bridge/fcc/hcp are undefined there.

Energies

r = adsorption_energy(slab, adsorbate="CO", site="ontop", scheme=None, fmax=0.1, steps=60)
# r: E_ads_eV (negative = exothermic), E_slab_eV, E_slab_ads_eV, E_ref_eV, scheme,
#    dz_A, converged, fmax_final, atoms (relaxed slab+adsorbate)
site_scan(slab, "CO", sites=("ontop","bridge","fcc","hcp"))   # {site: E_ads_eV}
ontop_scan(slab, "OH", max_sites=9)                            # [{index, symbol, E_ads_eV}, ...]
sabatier_activity(e_ads_list, e_ref_pt111, optimum=0.10)       # HEAgent-style score, 0..1

Adsorbates: O, H, N, C, S, CO, NO, N2, OH, OOH, H2O, NH, NH2, NH3, CH3, CHO, CO2, OCHO.

Reference schemes (scheme):

• "che" (default for O, OH, OOH, H, N): O = H2O - H2, OH = H2O - 1/2 H2, OOH = 2 H2O - 3/2 H2, H = 1/2 H2, N = 1/2 N2. Positive values are normal here (O on rutile cus is roughly +1 to +3 eV). Do not call them a sign error.
• "gas" (default for CO, NO, NH3, H2O, CO2): the molecule itself. Strong binders come out negative (CO on Pt(111) about -1.8 eV with MACE-MP-0 small).

Script skeleton the server expects

import json
from catagent_harness import build_slab, site_scan, adsorption_energy, save_structure

def run(fmax, steps, production=False):
    slab = build_slab("Pt", "111", size=(3, 3, 4))
    energies = site_scan(slab, "CO", sites=("ontop", "bridge", "fcc", "hcp"), fmax=fmax, steps=steps)
    best = min(energies, key=energies.get)
    if production:
        for s, e in energies.items():
            print(f"CASE Pt111_{s}_CO E_ads_eV={e} converged=True")
        r = adsorption_energy(slab, "CO", best, fmax=fmax, steps=steps)
        save_structure(r["atoms"], "structure.extxyz")
    return {f"Pt111_{s}_CO_E_ads_eV": e for s, e in energies.items()}

run(fmax=3.0, steps=3)            # smoke test, seconds
print("SMOKE_OK")
result = run(fmax=0.1, steps=60, production=True)
print("RESULT_JSON:" + json.dumps(result, separators=(",", ":")))

Rules the auditor enforces: smoke run first, SMOKE_OK, exactly one RESULT_JSON: line with only numbers, one save_structure call, no hard-coded reference energies, no repeat(), steps <= 80, size at most 4x4x4.

4. Worked examples (all verified on catagent.schoung.com, MACE-MP-0 small)

5. Reporting to the user

Give the table of E_ads per case with the scheme named, the most stable case, fmax_final and whether it met 0.1 eV/A, the MLIP used, and the wall time. Say "demo-grade MLIP estimate" in the first sentence. Link the structure and plot PNGs when they exist.