Surfaces, electrodes and nanoparticles

Surface partners are schematic drawing objects, not molecular species or physical slabs. They carry material, optional facet, substrate layers (bottom to top), particle diameter in nm, ligand-shell label and named attachment anchors. A later cluster or periodic builder can read this intent; this feature does not choose lattice constants, a unit cell, surface coverage or a calculation model.

Each object is one editable KET image. Move or resize it with the canvas image tools. The image carries bounded, validated JSON metadata with schema vibe-sketch-surface/1; SVG/PDF/PNG/EPS/EMF and chemfig redraw from that metadata, never embed the image’s SVG. Document.surfaces is derived from the drawing and lists the labelled generic structures currently meeting each anchor. Deleting an object removes its derived record. A copied object needs a distinct id.

Add, edit and graft

from vibesketch.document import new_document
from vibesketch.document.surfaces import with_surface, attach_to_surface

parameters = {
    "id": "gold",
    "kind": "electrode",
    "material": "Au",
    "facet": "111",
    "anchors": {"top": {"u": 0.5, "v": 0, "dx": 0, "dy": 1, "site": "bridge", "repeat": 12}},
}
document = with_surface(new_document(), parameters, width=8, height=3)
# After importing a labelled aryl structure as generic g1:
# document = attach_to_surface(document, "g1", "gold", "top")

Kinds are surface, electrode, stack, nanoparticle and nanotube-array. A stack requires layers, e.g. ["Si", "SiO2", "Al2O3"]. A nanoparticle requires a positive diameter_nm; ligand_shell is an optional plain label, for example phosphonate. Arrays require nanotube, the id of an existing generated nanotube species, and count (1–20): they reuse its schematic glyph turned vertically above the material substrate. This is a schematic array, not a spatially replicated atom model.

Anchors use fractions u,v of the image box (left to right, top to bottom), and a nonzero outward direction dx,dy in drawing coordinates (y up). The default anchor is top. Optional site is top, bridge or hollow. repeat (1–10,000) draws one linker with an explicit repeat count, without expanding its molecular graph. It is not a coverage in molecules per area. Multiple named anchors allow explicitly drawn rows of linkers.

Grafting reuses labelled attachment atoms: import an organic structure bonded to an alias such as Au, CNT or NP, then attach its generic id. The labelled atom moves to the anchor and its bond points outwards. Publication rendering suppresses that label at the join; the generic remains distinct from a calculable molecule. Capping it is a separate explicit operation.

Use these pieces for aryl grafting on Au, phosphonate linkers on SiO2 with a ligand-bearing nanoparticle, or an amide linker between a COOH-terminated tube and an aminophenyl-grafted Cu electrode. Chemical labels, arrows and conditions remain editable using the usual reaction drawing tools.

Calling with_surface with an existing id replaces its metadata and depiction. It preserves its top-left position unless at is supplied; pass the desired width and height again. Reattach a linker after moving or resizing its surface if its labelled atom no longer meets the anchor.

Other interfaces and formats

Write the parameter object above to surface.json:

vibe-sketch surface drawing.vsk surface.json --width 8 --height 3
vibe-sketch attach drawing.vsk g1 gold --anchor top

REST: POST /api/documents/{id}/surfaces accepts revision, parameters, optional at: [x,y], width, height; GET on the same path lists derived records. Stale writes return 409. The existing POST /api/documents/{id}/generics/{generic}/attach accepts a surface id in species and its anchor name. MCP exposes add_surface, list_surfaces and attach_to_surface with the same validated SDK operations.

QVF and VSK preserve the full document. KET preserves object metadata and rederives surface records on import. MOL, SDF, RXN, SMILES, InChI and CDXML refuse documents containing surfaces: they cannot express these partners. No surface is silently converted into a molecular species or omitted.