cluster-ops

Multi-atom edits — adsorbate placement, water layers, ion clusters, supercell expansion. The default exploration path lists catgo_structure actions, asks the analysis MCP for adsorption sites, eyeballs them, then composes a merge call manually. This skill collapses each case to a single MCP call with the correct parameters.

When to use this skill

• Placing a molecule or polyatomic adsorbate on a surface (add_molecule or analysis→merge).
• Building dual-adsorbate configurations for coupling reactions (C–N, C–C, N–N).
• Adding a water solvation layer on top of a slab.
• Building or expanding a supercell.
• Removing a previously-placed cluster (delete by indices spanning the cluster atoms).

If the user wants to edit a single atom (add H at coord, swap O for F, move atom 12, delete one atom), use the structure/atom_ops skill instead — atom-level ops have different MCP entry points.

Operation cheat sheet

Add a single small molecule at a Cartesian position

User: "Add a water molecule at (3.0, 3.0, 8.0)" or "加一个 H2O 在 slab 上方"

{
  "action": "add_molecule",
  "query": "water",
  "count": 1,
  "position": [3.0, 3.0, 8.0]
}

query accepts common names (water, methanol, ammonia, formate, co, oh, nh2, …) or formulas. If position is omitted, the molecule is placed near the structure centroid; specify position for placement above a slab.

Place an adsorbate on a surface (auto site selection)

User: "Place CO on a hollow site of the Cu(111) slab"

Two-step playbook:

1. Call catgo_analyze once to enumerate adsorption sites:

   {"action": "adsorption_sites"}
   

   The response lists sites with type (top/bridge/hollow/fcc/hcp) and [x, y, z] coordinates. Use it to pick the matching site type the user asked for; if multiple, pick the first one by default and tell the user "placed on the first hollow site — there are N total, ask to switch if needed".

2. Add the adsorbate at the chosen site, offset above the surface by the typical bond length:

   {
     "action": "add_molecule",
     "query": "CO",
     "count": 1,
     "position": [site_x, site_y, site_z + 1.8]
   }
   

   Typical bond-length offsets above the topmost slab atom:

   • C, N, O end-on to metal: 1.8 Å
   • C–C through carbon: 2.0 Å
   • H to metal (η¹-H): 1.5 Å
   • O of H₂O (η¹ oxygen): 2.2 Å

Do not call adsorption_sites more than once per turn. Re-use the same response if the user asks for several placements on the same slab.

Dual adsorbates for C–N (or any X–Y) coupling

User: "Place CO and NH2 on Cu(111), 3.5 Å apart, for C–N coupling slow-growth"

The CatGo server exposes a dedicated combined call (used by the AI workflow tutorial). Pattern:

1. catgo_analyze adsorption_sites once.
2. Pick two distinct sites whose Cartesian distance is closest to the requested separation (or just pick adjacent fcc-hcp pair on a (111) surface — typical distance ~2.5–3 Å on metals).
3. Two sequential add_molecule calls anchored at those sites, with adsorbates oriented so the coupling atoms face each other. The query accepts the molecule, and orientation is currently a follow-up edit.

If the user names a specific reaction (C–N coupling for nitrate-to-ammonia, urea synthesis, etc.), recommend the slow_growth workflow node with iconst="R i1 i2 0" where i1 and i2 are the atom indices of C and N after placement. The user usually wants to chain "place + slow-growth"; combine this skill with workflow_builder in a single response.

Add a water solvation layer on top of a slab

User: "Add a water layer 3 Å above the Cu surface" or "做水层"

Packmol-style placement using add_molecule with count > 1:

{
  "action": "add_molecule",
  "query": "water",
  "count": 16,
  "spacing": 2.8,
  "position": [center_x, center_y, top_z + 3.0]
}

• count = 16 is a typical 1-monolayer coverage for a 2x2 surface. For larger cells scale ~density: 4 waters per ~6×6 Ų of surface area.
• spacing = 2.8 Å matches the average O–O hydrogen-bond distance.
• top_z + 3.0 places the centre of the cluster ~3 Å above the topmost slab atom.

The result is a Packmol-packed cluster of waters above the slab. Tell the user the count and the layer height, and offer to follow with an MD equilibration step (an NVT MD node at 300 K, 2000 steps) if they want a physically reasonable starting geometry instead of a frozen packed configuration.

Build a supercell

User: "Make a 2x2x1 supercell" / "做超胞 3×3×1"

{"action": "supercell", "scaling": [2, 2, 1]}

For non-diagonal supercells (anisotropic strain studies, twisted bilayer commensurate cells), pass a matrix (3×3 integers) instead of scaling.

If the user asks for a supercell of a slab, do it after slab generation, not before — supercelling a bulk and then slabbing along an oblique direction can change the actual surface orientation. The same constraint matters for adsorbate placement: supercell before placing the adsorbate so the placement is the right multiplicity, otherwise the adsorbate gets duplicated.

Merge an external structure (cluster, fragment, molecule from file)

User: "Drop this ammonia cluster I just loaded onto the slab"

{"action": "merge", "structure": <pymatgen-dict>, "position": [x, y, z]}

Use this when the incoming fragment is not a standard library molecule (add_molecule covers common species). The structure argument is the pymatgen dict for the incoming fragment; the position is where to place its centroid.

Remove a previously-placed cluster

User: "Remove the CO I just placed" or "删掉刚才的水层"

CatGo flags placed clusters' atom indices in the action response. Re-use those indices in a single delete call from the structure/atom_ops skill ({"action":"delete","indices":[...]}). If you don't have the indices, calling get once and filtering by element / Cartesian range is acceptable but slower; prefer keeping the indices from the previous placement turn.

What NOT to do

• Calling adsorption_sites repeatedly within a chat turn — the site list does not change unless the slab changes, so cache it.
• Calling add_molecule once per atom of a polyatomic adsorbate. The skill is add_molecule (one call per molecule, not per atom).
• Picking a placement height by visual inspection of the structure summary. The bond-length offsets above are calibrated and produce starting geometries within ~0.3 Å of relaxed positions.

After-edit confirmation

One sentence. Name the species, where it was placed (site type, fractional or "above topmost atom by X Å"), and the new total atom count.

Placed CO on the first fcc-hollow site of Cu(111), 1.8 Å above the surface. Structure now has 26 atoms. Added a 16-water layer 3 Å above the slab (Packmol-packed, O–O spacing 2.8 Å). 92 atoms total. Made a 2x2x1 supercell. 48 → 192 atoms.

Do not dump the full coordinate list — the viewer renders the result.