Update to Vibe Catalysis

{
  "description": "Build and run local heterogeneous-catalysis adsorption calculations with ASE and FAIR-Chem UMA. Use when a user asks Codex to model, relax, rank, inspect, or estimate adsorption energies for CO, CHO/HCO, COH, CHOH, or CH2OH on a generated elemental fcc/bcc/hcp surface or a user-supplied catalyst slab/framework such as a COF, MOF, oxide, nitride, supported catalyst, CIF, POSCAR/CONTCAR, XYZ/EXTXYZ, or TRAJ; also use for the Vibe Catalysis ten-step workflow, adsorption-site enumeration, active-atom selection, fixed slab layers, UMA relaxation, data processing, plots, or generated structure/result files.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 308
    },
    {
      "relative_path": "scripts/predict_adsorption.py",
      "size_in_bytes": 28756
    },
    {
      "relative_path": "scripts/run_local.py",
      "size_in_bytes": 2758
    },
    {
      "relative_path": "scripts/visualize_results.py",
      "size_in_bytes": 16439
    }
  ],
  "name": "vibe-catalysis",
  "skill_md_contents": "---\nname: vibe-catalysis\ndescription: Build and run local heterogeneous-catalysis adsorption calculations with ASE and FAIR-Chem UMA. Use when a user asks Codex to model, relax, rank, inspect, or estimate adsorption energies for CO, CHO/HCO, COH, CHOH, or CH2OH on a generated elemental fcc/bcc/hcp surface or a user-supplied catalyst slab/framework such as a COF, MOF, oxide, nitride, supported catalyst, CIF, POSCAR/CONTCAR, XYZ/EXTXYZ, or TRAJ; also use for the Vibe Catalysis ten-step workflow, adsorption-site enumeration, active-atom selection, fixed slab layers, UMA relaxation, data processing, plots, or generated structure/result files.\n---\n\n# Vibe Catalysis\n\nRun the deterministic local backend; do not generate ad hoc ASE calculation\ncode when the validated backend can perform the request.\n\n## Resolve the local runtime\n\nUse the backend bundled with this installed skill:\n\n```text\nPython: a Python 3.12 environment containing ASE, fairchem-core, NumPy, and Matplotlib\nBackend: scripts/predict_adsorption.py\nLauncher: scripts/run_local.py\n```\n\nRun `python3 scripts/run_local.py --check` before the first calculation in a task.\nThe launcher must choose the working runtime reported by that check; it searches\n`VIBE_CATALYSIS_PYTHON` and common `cathub-uma` Conda locations, so the Python\nused to start the launcher does not itself need ASE. Stop and explain the missing\ndependency only if this launcher check fails after its search. Never request or print the\nHugging Face token; FAIR-Chem reads the existing local login and cached model.\nThe user must separately obtain access to the gated `facebook/UMA` model and\nauthenticate through Hugging Face. Access and model weights are not bundled.\n\n## Translate the request\n\nExtract:\n\n- structure source: either an attached/local catalyst structure readable by ASE, or an\n  elemental metal whose ASE reference state is `fcc`, `bcc`, or `hcp`;\n- facet for generated slabs: fcc `111`/`100`/`110`, bcc `111`/`100`/`110`, or\n  hcp `0001`/`10-10`;\n- adsorbate: `CO`, `CHO`, `COH`, `CHOH`, or `CH2OH`;\n- optional slab size, sites, anchors, vacuum, fixed layers, `fmax`, and steps.\n\nTreat `CHO`/`HCO` as the formyl isomer. Keep `COH` distinct. If the user omits\nsettings, use 3×3×4 (3×4×4 for hcp(10-10)), 10 Å vacuum, bottom two\nlayers fixed, `fmax=0.05 eV/Å`, and at most 100 LBFGS steps. Infer the stable\ncrystal structure from ASE. If the facet is omitted, use fcc(111), bcc(110),\nor hcp(0001). Run one metal per job; multiple requested adsorbates may run as\nseparate child calculations under one comparison directory.\n\nWhen the user supplies a structure, resolve its local absolute path and pass it\nwith `--structure`; do not require a metal or facet. Treat **every atom already\nin the file as part of the catalyst/framework**, even C, O, N, or H. Never infer\nadsorbates from element identity. Only the species explicitly requested for\naddition is the new adsorbate. Never modify or overwrite the uploaded source. CIF, POSCAR/CONTCAR,\nXYZ/EXTXYZ, TRAJ, and any other format readable by ASE are acceptable, but CIF\nusually cannot preserve VASP selective-dynamics constraints. Do not attempt to\ndecompose a pre-existing combined structure into catalyst and adsorbate unless\nthe user explicitly supplies atom membership or paired-state inputs.\n\n## Execute the ten-step workflow\n\n1. Build a supported elemental slab, or read the user-supplied catalyst/framework structure without changing the source or reclassifying its atoms.\n2. Validate its 3D cell, in-plane periodicity, and approximate vacuum; for generated structures, add vacuum and surface-plane periodicity.\n3. Preserve constraints read by ASE; if none exist, apply `FixAtoms` to the bottom two layers. Replace uploaded constraints only when the user explicitly asks.\n4. Build and independently relax the gas-phase molecular/isomer reference and H₂ for CHE hydrogenation energies.\n5. For generated slabs, enumerate ASE's named sites for that exact surface. For uploaded slabs, discover indexed ontop, bridge, and threefold-hollow coordinates from top-layer atoms. For COFs, MOFs, porous/multicomponent materials, defects, and supported catalysts, prefer user-selected zero-based `--active-atom-indices` or explicit `--site-xy X Y` coordinates over blind top-layer discovery.\n6. Enumerate C-down/O-down for CO; enumerate 0/120/240° azimuths for larger intermediates.\n7. Calculate UMA single-point energies with the `oc20` task.\n8. Run constrained ASE LBFGS relaxation for the clean slab and every candidate.\n9. Flag desorption, surface penetration, internal bond breaking, large reconstruction, non-convergence, and calculation failure.\n10. Rank only accepted candidates and save a candidate table, summary, initial/final structures, logs, trajectories, best structure, and automatic energy/top-view visualization.\n\nWrite each job to a new directory under the active task's `outputs/`. Use an\nexplicit absolute `--output` path. Never overwrite an existing result directory.\n\nInvoke:\n\n```bash\n<python-with-ase-and-fairchem> scripts/run_local.py \\\n  --metal Fe --facet 110 --adsorbate CO --output /absolute/task/outputs/CO_Fe110\n```\n\nFor an uploaded structure:\n\n```bash\n<python-with-ase-and-fairchem> scripts/run_local.py \\\n  --structure /absolute/path/POSCAR --adsorbate CO \\\n  --output /absolute/task/outputs/CO_uploaded\n```\n\nFor a framework with known active atoms:\n\n```bash\n<python-with-ase-and-fairchem> scripts/run_local.py \\\n  --structure /absolute/path/cof.cif --adsorbate CO \\\n  --active-atom-indices 18 24 31 \\\n  --output /absolute/task/outputs/CO_COF\n```\n\nPass supported backend overrides after the launcher arguments, for example\n`--size 2 2 4`, `--sites ontop bridge`, or `--single-point-only`.\n\n## Interpret and report\n\nUse the backend definition:\n\n```text\nE_ads(X) = E_UMA(slab + X) - E_UMA(clean slab) - E_UMA(X gas)\n```\n\nFor proton-electron hydrogenation such as `CO* + H+ + e- -> CHO*`, do not\nsubtract independently referenced adsorption energies. Use the best relaxed\ntotal energies from the same slab model and the bundled relaxed H₂ reference:\n\n```text\nDeltaE_CHE(CO* -> CHO*) = E(CHO*) - E(CO*) - 1/2 E(H2)\nDeltaG_CHE_approx(U,pH) = DeltaE_CHE + eU + kB*T*ln(10)*pH\n```\n\nPotential defaults to `U=0 V vs SHE`, `pH=0`, and `T=298.15 K`. For multiple\nmembers of the CO/CHO/COH/CHOH/CH2OH family, run `scripts/visualize_results.py`\non the completed job directories; it automatically writes `che_energies.csv`,\na CHE JSON record, and the energy profile. Pass `--potential-v`, `--ph`, and\n`--temperature-k` when the user specifies electrochemical conditions.\nWrite both `che_energies.csv` for cumulative state energies and\n`che_reaction_energies.csv` for directed-step energies. Report the inferred\ntopology: `single_reaction`, `branch_comparison`, or `sequential_path`.\n\nReport runtime, candidate count, accepted/rejected count, rejection reasons,\nlowest accepted site/orientation, adsorption energy, convergence, and clickable\nlinks to `summary.json`, `candidates.csv`, `best_structure.extxyz`, and\n`energy_and_topviews.png`.\nFor uploaded structures, also report the source filename, SHA-256 provenance,\nwhether input constraints were preserved, estimated vacuum, discovered site\ncount, active-atom selection, and validation warnings from `summary.json`.\n\nUse reaction topology, not merely the number of states, to choose a chart. One\nreaction energy becomes a numerical card. Two or more independent reactions\nsharing a reactant, such as `CO* -> CHO*` versus `CO* -> COH*`, become a\nreaction-energy bar chart. Only a genuinely consecutive path with at least two\nconnected steps and three states, such as `CO* -> CHO* -> CHOH*`, becomes a\nstep-style profile. Never connect competing products as if one converted into\nthe other. Multiple sites remain a lowest-energy-per-site bar chart. Include\nASE-native relaxed-structure top views with standard element colours, radii,\nand the periodic unit cell. Use the bundled publication theme: Times New Roman,\nTimes, or DejaVu Serif fallback; STIX math; 1.8-point axes and major ticks;\n7-point major tick length; 11--19 point text hierarchy; and 300 dpi PNG output.\nLabel a multi-adsorbate profile as independently\nreferenced adsorption energies, not a balanced reaction or free-energy diagram.\nA CHE electronic-energy diagram uses a consistent H₂ chemical potential, but\nis not a full free-energy diagram unless ZPE, entropy, solvation, field and\nother requested corrections are supplied.\n\nAlways label the result:\n\n> UMA prediction on an ASE-generated or user-supplied structure; not a Catalysis-Hub DFT benchmark.\n\nASE reference-state support means the structure can be generated; it does not\nshow that UMA is accurate for that element, magnetic state, or surface. Do not\npresent a high-symmetry site ranking as experimentally validated. Mention\nthat finite site/orientation enumeration can miss lower-energy structures and\nthat solvent, potential, defects, coverage variation, co-adsorbates, and\ntransition states are outside this workflow.\nAutomatic site discovery on uploaded reconstructed, stepped, porous, defective,\nor multicomponent slabs is a screening heuristic. Require visual inspection of\nthe ASE-native top views before interpreting its ranking.\n\nFor a strict DFT comparison, use the repository's separate Catalysis-Hub\nbenchmark path only when a matched structure and consistent reference are\navailable; never compare unlike energy definitions.\n"
}