SOAgent skill

SOAgent turns one plain-language question ("O vacancy formation energy in La0.6Sr0.4CoO3") into a relaxed perovskite-oxide calculation with a machine-learned interatomic potential (MLIP) and returns numbers, a plot and a rendered structure. Web UI: https://soagent.schoung.com. Source of this skill: https://github.com/s-choung/Research-Skills/tree/master/skills/soagent.

Use it when the user wants demo-grade (fmax 0.1 eV/A, 2x2x2 supercell) solid-oxide material property estimates in about 1 to 4 minutes, not publication-grade DFT.

1. Remote mode: HTTP API

Base URL https://soagent.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. There is no local harness file for SOAgent — remote mode only.

1.1 Plan (LLM, ~5 s)

curl -s https://soagent.schoung.com/api/plan \
  -H 'content-type: application/json' \
  -d '{"message": "La0.6Sr0.4CoO3에서 산소 공공 형성 에너지를 계산해줘.", "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. spec.estimated_runtime_s gives the expected wall time.

1.2 Write the script (LLM, ~15 s)

curl -s https://soagent.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 the fixed SOAgent harness (section 3). mlip is one of mace-small (MACE-MP small, default, fastest) or matpes-r2scan (MACE MatPES r2SCAN). 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://soagent.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://soagent.schoung.com/api/preview -H 'content-type: application/json' \
  -d '{"code": "<script>", "mlip": "mace-small"}'
# -> {"runId": "run_...", "structures": ["/live/run_.../preview_structure_0.png", ...]}

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://soagent.schoung.com/api/simulate -H 'content-type: application/json' \
  -d '{"code": "<script>", "mlip": "mace-small", "taskId": "lsc_ovac", "previewRunId": "run_..."}'
# -> {"jobId": "job_..."}
curl -s 'https://soagent.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. 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 or GPa, plus CASE <label> ... lines and [harness] ... lines noting which structures came from the local OPTIMADE snapshot vs. an ideal cell. Parse RESULT_JSON from output yourself, or ask the analyzer:

curl -s https://soagent.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 compositions from a script. A handful of 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 whether the relax converged. Demo-grade means fmax 0.1 eV/A on a 2x2x2 (up to 48-atom) supercell.

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

from soagent_harness import (
    get_calculator, load_optimade, reference_bulk, get_o2_energy,
    relax, build_perovskite, build_fluorite, substitute,
    ovac_formation, eos_bulk_modulus, surface_energy, mu_metal,
    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

Relax and energies

e = relax(atoms, fmax=0.1, steps=50, cell=True)
# e is a float (final energy, eV) that also proxies the relaxed Atoms object
# (iterate/index/attribute-access it directly). Refuses cell relaxation
# when vacuum is present (slab/molecule) to avoid corrupting energies.

e_o2 = get_o2_energy(fmax=0.1, steps=50)
# Reference O2 molecule energy (eV), fixed 12 A box, positions-only relax.
# NEVER cell-relax a gas-phase reference.

e_vac = ovac_formation(bulk_atoms, fmax=0.1, steps=50, o_index=None)
# O vacancy formation energy (eV) for one representative O site (defaults
# to the first O atom). Pass prerelaxed=True if bulk_atoms is already
# relaxed to skip a redundant bulk relaxation.

eos = eos_bulk_modulus(atoms, fmax=0.1, steps=50, n_points=7, span=0.03)
# Relax then Birch-Murnaghan EOS fit.
# -> {"bulk_modulus_GPa": ..., "V0_A3": ..., "E0_eV": ...}

surf = surface_energy(prim_atoms, miller=(0,0,1), layers=4, vacuum=15.0, fmax=0.1, steps=50)
# Surface energy (eV/A^2) from a PRIMITIVE bulk cell.
# -> {"surface_energy_eV_A2": ..., "n_atoms_slab": ..., "slab": <Atoms>}
# Raises if the generated slab exceeds 60 atoms - pass a primitive cell.

mu = mu_metal("Sr", fmax=0.1, steps=50)
# Chemical potential (eV) of a metal in equilibrium with its binary oxide
# and O2 - the correct reservoir for substitution/doping energies in
# oxides. Defined for La, Pr, Sm, Nd, Gd, Y, Yb, Sr, Ca, Ba, Ce.

save_structure(atoms, filename="structure.extxyz") exports safely (strips the calculator and any stray arrays) and must be called exactly once per script.

Script skeleton the server expects

import json
from soagent_harness import build_perovskite, relax, ovac_formation, save_structure

def run(fmax, steps, production=False):
    bulk = build_perovskite("La", "Co", supercell=(2, 2, 2))
    e_bulk = relax(bulk, fmax=fmax, steps=steps, cell=True)
    e_vac = ovac_formation(bulk, fmax=fmax, steps=steps, prerelaxed=True)
    if production:
        print(f"CASE LaCoO3_Ovac E_vac_eV={e_vac} converged=True")
        save_structure(bulk, "structure.extxyz")
    return {"LaCoO3_Ovac_E_vac_eV": e_vac}

run(fmax=3.0, steps=3)            # smoke test, seconds
print("SMOKE_OK")
result = run(fmax=0.1, steps=50, 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, steps <= 80, supercell at most 4x4x4.

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

4. Reporting to the user

Give the requested property with the scheme and site named, fmax_final and whether it met 0.1 eV/A, the MLIP used (mace-small or matpes-r2scan), and the wall time. Say "demo-grade MLIP estimate" in the first sentence. Link the structure and plot PNGs when they exist.