Cluster Ops

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.