vibe-sketcherDocumentation

CNT–linker–metal junctions

kind: "cnt_junction" builds a covalent junction between a carbon nanotube, a molecular linker and a metal surface site. Every part and every bond is chosen explicitly. Nothing is perceived from distances or guessed. The record lists each bond the assembly added and why.

A junction is an unrelaxed construction. It is not a relaxed geometry, a binding or reaction energy, a conductance or transport result, or a validated atomistic junction. The record says so under status and not_claimed. The most stable site is not chosen for you either. In the source calculations, most starting sites relax to a different final site.

What the model contains

The junction has three parts.

  • Tube. A finite single-walled (n,m) tube of periods translation periods. The default is the source’s open-ended (8,0) tube; 4 periods give 17.0 Å against the source’s 15 Å. Both rims are hydrogen-capped, one H per two-coordinate rim carbon at 1.09 Å. attachment chooses how the tube bonds:

    • end_on bonds an open-end rim carbon to the linker. That carbon takes the linker bond instead of a hydrogen cap; this is recorded as a complete_valence edit.

    • sidewall bonds a wall carbon of the central period and turns it from sp2 to sp3. Its three tube bonds become single bonds. The rehybridise edit lists them.

    attachment_carbon is an index into the list that junction-carbons prints.

  • Linker. A SMILES string with two connection markers: [*:1] points to the tube and [*:2] to the metal. The default is [*:1]C(=O)Nc1ccc([*:2])cc1. This is the amide-linked aminophenyl group of the source. The CNT carboxyl and the grafted aminophenyl amine react to an amide and water, and the former diazonium carbon bonds to the metal. The linker is embedded with RDKit using a fixed seed. The bond to the metal points along the [*:2] marker, straight down to the site. The tube bond follows the [*:1] marker vector, so the linker’s chemistry sets how the tube is tilted.

  • Metal site. A slab cut from the Cu or Au crystal template, with layers atomic planes and repeat in-plane cells. Then name a site:

Facet

site

site_variant

Metal atoms bonded

Cu(100)

top, bridge, hollow

none

1, 2, 4 (four-fold)

Cu(110)

top, bridge, hollow

bridge: short (along [1-10]) or long (along [001])

1, 2, 4

Cu(111), Au(111)

top, bridge, hollow

hollow: fcc or hcp

1, 2, 3

A hollow on fcc(111) is hcp when a second-layer atom lies beneath it, and fcc otherwise. The reference atom is surface_atom. When it is unset, the builder takes the top-layer atom nearest the in-plane cell centre and records it. site_index picks one of the equivalent sites around that atom, in azimuth order. junction-sites lists them all.

Distances and their sources

The primary source is C. P. Nawarathne, A. Hoque, G. R. Dangel and N. T. Alvarez, Creating covalent bonds between Cu and C at the interface of metal/open-ended carbon nanotubes, Nanoscale Adv. 6, 428 (2024), doi:10.1039/d3na00500c, Table 1. The builder uses only values stated in the main text. The ESI is not in the literature library, so no ESI value is used.

Facet and final site

Cu–C placement distance

Table 1 row (most stable start)

Cu(100) bridge

2.08 Å

hole → bridge

Cu(110) bridge

2.05 Å

top → bridge

Cu(111) bridge

2.02 Å

hole → bridge

Cu(111) top

1.97 Å

top → top

These are distances of the paper’s optimised structures. The builder uses them only to place atoms. Every other site has no source value: Cu hollow sites, Cu(100) and Cu(110) top sites, and all Au sites. Those relax to bridge in the source or were not computed. For them the default is the sum of RDKit covalent radii (Cordero et al. 2008), and the record marks it illustrative. The sidewall studies on Cu and Au (doi:10.1021/acsanm.3c04137) and the Au-film study (doi:10.1021/acsami.4c19859) are experimental and give no junction geometry. You can state your own metal_carbon_distance.

The bonded linker carbon sits at a height of √(d² − ρ²) above the site. Here d is the metal–carbon distance and ρ the site’s in-plane radius. A distance that cannot reach the site is refused. The illustrative 2.08 Å cannot reach a Cu(110) hollow, whose radius is 2.21 Å. The tube–linker bond is 1.50 Å, an illustrative single bond. The tube’s rotation about that bond is chosen on a 5° grid. The grid value with the largest contact to the slab and linker wins, then the one farthest from the tube’s in-plane images. Each contact counts up to 3 Å. Ties go to the higher tube, then the smaller angle. Set cnt_rotation_deg to choose the rotation yourself.

Boundary policy and checks

  • slab_2d (default): the slab is periodic in-plane, PBC (T, T, F), with vacuum along the normal. slab_3d pads the same model into a 3-D cell. The tube and linker stay finite and hydrogen-capped, but they see their own in-plane images. Images closer than min_image_separation (3 Å) are refused. Enlarge repeat when that happens.

  • cluster is refused in this version. A finite metal cluster would need a stated shape, size and termination.

  • Clashes. Any unbonded pair closer than clash_fraction (0.75) times the sum of covalent radii is refused. Periodic images count too. An example is the long Cu(110) bridge, where the ring’s ortho hydrogens meet the surface.

  • Atom budget. More than max_atoms atoms (default 1500) is refused.

  • Charge and spin. charge, multiplicity and charge_spin_source are all required. A multiplicity that does not fit the electron count is refused. Nothing is compensated or inferred.

Refusals carry a code: junction.facet, site_variant, site, site_index, site_height, linker, attachment_carbon, atom_budget, image_separation, clash, charge_spin or boundary. Every code starts with junction..

Record

The structure’s provenance.builder.junction holds:

  • site: the facet, label, metal atoms, radius and index of the chosen site;

  • metal_carbon_distance: the value and its source;

  • linker: the SMILES, formula and connection points;

  • tube: the chirality, length, attachment site, caps and rotation rule;

  • graph_edits: every add_bond with its rationale, then the rehybridise or complete_valence edit and the cap_hydrogen bonds;

  • boundary, checks and charge_spin;

  • the source block, not_claimed, and a site map that gives each atom’s part (metal, linker, cnt or cap).

Metal–metal bonds are not authored. Perceive them with the periodic graph tools when you need them. The structure round-trips through .vsk and QVF. The vibe-qc periodic writer accepts it and writes the stated charge and multiplicity.

SDK, CLI, REST and MCP

from vibesketcher.document import new_document
from vibesketcher.document.solid_build import build, parse_recipe
from vibesketcher.document.cnt_junctions import surface_sites, attachment_candidates

surface_sites("Cu", (1, 1, 1))  # the explicit site catalogue
attachment_candidates(8, 0, 4, "end_on")  # what attachment_carbon indexes
doc = build(
    new_document(),
    parse_recipe(
        {
            "kind": "cnt_junction",
            "identifier": "cnt-cu111",
            "metal": "Cu",
            "miller": [1, 1, 1],
            "site": "bridge",
            "attachment": "end_on",
            "attachment_carbon": 0,
            "charge": 0,
            "multiplicity": 2,
            "charge_spin_source": "neutral; doublet from the odd electron count",
        }
    ),
)
vibe-sketcher solid junction-sites --metal Cu --miller 110
vibe-sketcher solid junction-carbons --attachment sidewall --periods 2
vibe-sketcher solid cnt-junction junction.vsk --id cnt-cu111 --metal Cu --miller 111 \
    --site bridge --attachment end_on --attachment-carbon 0 \
    --charge 0 --multiplicity 2 --charge-spin-source "stated" --preview

The REST routes are POST /api/periodic/cnt-junction/sites, POST /api/periodic/cnt-junction/carbons and POST /api/documents/{id}/periodic/cnt-junction/preview. Building goes through POST /api/documents/{id}/periodic/build with the recipe. The MCP tools are cnt_junction_sites, cnt_junction_carbons and preview_cnt_junction. Build with build_periodic.

Not yet covered

  • A browser form.

  • Finite metal clusters.

  • A tube that is periodic along the surface.

  • Multi-walled tubes.

  • Several linkers on one tube.

  • Paper-specific reconstruction of the ESI slab sizes and k-point settings.