Nanostructures¶
vibe-sketch generates carbon nanotubes, graphene flakes, graphene nanoribbons and fullerenes from their parameters instead of having them drawn atom by atom. The result is a species of the document: a finite cluster model with its 3D atoms, its bonds, a charge and a multiplicity, which the input writers take like any other species and which opens in vibe-view as a QVF.
A nanostructure is not drawn on the canvas, so it is never laid out in 2D and the 2,500-atom layout bound does not apply to it; the 25,000-atom bound on a document’s atoms does, and is checked before any atom is made. Redrawing the canvas keeps it. On the canvas and in figures it is one picture.
Build a nanotube in the browser¶
Choose Templates… → Custom nanotube…. Enter wall chiralities as n,m
pairs separated by semicolons, innermost first (for example
5,5; 10,10; 15,15). Choose length, lower and upper end groups, charge,
optional spin multiplicity and depiction. An empty spin field chooses the
lowest multiplicity allowed by electron parity, not a predicted ground state.
Insert nanotube adds the finite model and its picture in one edit.
Automatic species IDs skip identifiers already used by surfaces and other
document records; an explicitly requested duplicate ID is refused.
Invalid wall spacing, unsupported caps or atom-limit requests leave the
document unchanged and keep the entered values for correction. Moving and
resizing the inserted picture works as for preset templates. Optional Sidewall groups and Defects fields use semicolon-separated
name@fraction,angle entries, for example OH@0.5,0; COOH@0.7,180
and vacancy@0.3,90. Groups are H, OH or COOH; defects are
vacancy or stone-wales. The fraction is 0–1 and angle is at least 0
and less than 360 degrees. Sites select the nearest outer-wall carbon;
touching sites are refused without changing the document. These are the same
parameters available through SDK, CLI, REST and MCP.
Nanotubes¶
A nanotube is given by its chiral indices (n, m), with 0 ≤ m ≤ n, after the chiral-vector construction (Saito, Dresselhaus and Dresselhaus, Physical Properties of Carbon Nanotubes, 1998; Hamada, Sawada and Oshiyama, Phys. Rev. Lett. 68, 1579, 1992). With a = √3 × 1.42 Å:
Quantity |
Formula |
|---|---|
diameter |
d = a √(n² + nm + m²) / π |
chiral angle |
cos θ = (2n + m) / (2 √(n² + nm + m²)); 0° zigzag, 30° armchair |
translation period |
|T| = √3 |Ch| / d_R, d_R = gcd(2m + n, 2n + m) |
carbons per period |
2N, N = 2(n² + nm + m²) / d_R |
electronic character |
metallic when n − m is divisible by 3, else semiconducting (zone folding; curvature opens a small gap in thin non-armchair tubes) |
The summary of a nanotube lists these for each wall.
Parameter |
Meaning |
|---|---|
|
One |
|
The length in nm, or in translation periods of the innermost wall. Each wall gets the whole number of its own periods nearest that length. |
|
The lower and upper end: |
|
Groups bonded to the outer wall: |
|
|
A site is {along, around}: the fraction of the length (0 to 1) and the
angle about the axis in degrees. The nearest carbon of the undecorated tube is
taken, so one site never moves another; two that touch the same carbons are
refused.
Ends. An open end is cut at a whole period; carbons left with a single neighbour are removed and every two-coordinated carbon is terminated. A hydroxyl or carboxyl goes on an edge carbon only where it fits, in the sheet’s plane or turned about its bond to the twist with the most room; where it would touch a neighbour, that carbon gets hydrogen instead. So a carboxylated armchair end carries a carboxyl on one carbon of each pair.
Caps. A capped end is generated for a single-walled (5,5) tube only: C60 seen along a five-fold axis is two hemispheres ending in rings of ten, which are rings of a (5,5) tube, so a capped (5,5) tube is C60 with two rings per period inserted at its equator. Other chiralities need a search over cap isomers, which vibe-sketch does not do, and are refused.
Defects. A vacancy removes one carbon and leaves its three neighbours unsaturated. A Stone–Wales defect turns the C–C bond from the chosen carbon that lies most nearly along the axis by 90° (Stone and Wales, Chem. Phys. Lett. 128, 501, 1986), making two pentagons and two heptagons.
A 10 nm (10,10) tube is C1640H40 (41 periods of 40 carbons); the three-walled (5,5)@(10,10)@(15,15) segment of the same length is C4920H120.
Graphene, ribbons and fullerenes¶
Kind |
Parameters |
|---|---|
|
|
|
|
|
|
A site on a sheet or ribbon is {along, across}, both fractions.
Pictures in figures and on the canvas¶
A nanostructure is drawn the way papers draw it, never as thousands of labelled atoms:
Style |
What it shows |
|---|---|
|
The side projection of the lattice: the front wall solid, the rear wall light grey or left out ( |
|
A tube’s outline with the front wall’s hexagons as a light texture, for schemes; inner walls show as rings at the left end. |
|
A tube’s cross-section, one ring per wall. |
|
The sheet the innermost wall is rolled from, with the chiral vector Ch and the translation vector T. |
schematic, end-on and unrolled draw nanotubes only; other kinds are
refused with the reason. label prints (n,m), the outer diameter and the
number of walls under the picture. A tube longer than six diameters has its
middle cut out and a break mark (break: auto, on or off). Lines take
the style preset’s width, thinner for the lattice; grey marks the rear wall
and the texture, and colour is not used.
vibe-sketch depict tubes.vsk nano1 --style schematic --label
vibe-sketch depict tubes.vsk nano2 --style lattice --rear omit --break off
On the canvas a picture is one object, an image the canvas engine moves and resizes. Its SVG carries the species, its key, the style and the anchors, so every figure (SVG, PNG, PDF, EPS, EMF) and the chemfig export draw the picture afresh from the species’ atoms, in the figure’s preset, in the image’s box. The SVG stored in the canvas is never itself put into a figure. A picture whose species is gone, or any other image, is refused.
Anchors are where molecules attach: lower-end and upper-end at a
tube’s ends and sidewall on its upper side. Draw the molecule with a
labelled attachment atom such as
CNT, then move it onto an anchor:
vibe-sketch attach tubes.vsk g1 nano1 --anchor upper-end
The attachment atom is put on the anchor and the molecule turned so its bond
leaves the tube outwards. Figures then leave out the CNT label there, so
the bond meets the tube and the two print as one structure: a carboxylated
tube tip amide-bonded to an aminophenyl linker, for example.
Editing a drawing with the 10 nm three-walled segment (5,040 atoms) and a picture of it stays within the large-case budget of performance: a canvas edit took about 0.04 s and a figure about 0.4 s on an Apple M5 Max (not the reference machine), with about 5 MB of Python memory.
Identity, charge and spin¶
A nanostructure has no SMILES or InChI. Its identity is the canonical form
of its parameters, with a tube’s length resolved to whole periods per wall,
and its key is NANO- followed by 20 hexadecimal digits of that form’s
SHA-256. The same tube asked for in nanometres or in periods has one key; any
other end group, wall or site is another. The key is checked against the
parameters when a document is read, and the first conformer against the
recorded formula.
The multiplicity defaults to the lowest the electron count allows (a singlet, or a doublet for an odd count, as for a 1 × 1 nm flake, C43H17); a charge and multiplicity that do not fit are refused. Coordinates are a starting geometry: bond lengths are the lattice’s 1.42 Å and standard values for the groups, and sp3 carbons stay where the lattice put them. Optimise before reading geometry from them.
A single-walled tube or a ribbon without groups or defects also records its
one-dimensional cell (periodic: translation and carbons per period) for a
periodic model later; nothing writes a periodic input from it yet.
Every interface¶
vibe-sketch nanostructure tubes.vsk nanotube --wall 10,10 --length 10
vibe-sketch nanostructure tubes.vsk nanotube --wall 5,5 --concentric 3 --length 10 --ends COOH,H
vibe-sketch nanostructure tubes.vsk nanotube --wall 10,10 --periods 20 --sidewall COOH@0.5,0 --defect stone-wales@0.3,90
vibe-sketch nanostructure tubes.vsk nanoribbon --edge armchair --width 7 --periods 10
vibe-sketch nanostructure tubes.vsk fullerene --size 60
The document is created when it does not exist; --parameters JSON takes the
whole parameter object instead of the options. Then vibe-sketch info shows
each structure’s formula, masses and key, and vibe-sketch input writes it
for a program, xyz included.
from vibesketch.document import new_document, save
from vibesketch.document.nanostructures import with_nanostructure
document, made = with_nanostructure(
new_document(),
{"kind": "nanotube", "walls": [{"n": 10, "m": 10}], "length_nm": 10, "ends": ["COOH", "H"]},
)
print(made["formula"], made["key"])
save(document, "tube.vsk")
vibesketch.chem.nanostructures has the formulas (diameter_nm,
chiral_angle_deg, translation_angstrom, hexagons_per_period,
concentric_walls) and build, which returns the atom model without a
document. REST: POST /api/documents/{id}/nanostructures with the revision,
parameters and optionally species_id, label, charge and
multiplicity; the response carries the document and a nanostructure
summary, and a refusal is a 422 with the reason. MCP: add_nanostructure.
Pictures: SDK with_picture, pictures and attach_to_picture in
vibesketch.document.nanostructures; CLI depict and attach; REST
POST /api/documents/{id}/species/{species}/picture (revision, style,
label, rear, break, width), GET /api/documents/{id}/pictures and
POST /api/documents/{id}/generics/{generic}/attach (revision, species,
anchor); MCP depict_nanostructure and attach_to_nanostructure.
To generate and depict atomically through the other interfaces, use SDK
with_nanostructure(..., picture_style="schematic", picture_label=True),
CLI nanostructure ... --picture schematic --picture-label, or the optional
picture_style and picture_label fields on REST nanostructures and MCP
add_nanostructure. Omitting the style preserves model-only generation.