vibesketch.document.generics

Generic structures in the drawing as document entries: R-group cores, their definitions and bracketed groups (#90).

They are derived from the drawing like species, and written as CXSMILES without coordinates: R-group atoms carry their labels ($_R1$), a definition’s attachment points _AP1, and brackets their S-groups (Sg:n:...). The drawing stays the source of truth; nothing here is edited by clients (maintainer decisions, 2026-10-24).

Functions

attachment_labels(mol)

The labels of a structure's attachment atoms (CNT, Au, ...), in atom order (#139).

cap_labelled(document, generic_id, cap)

document with a species made by capping a labelled structure, and that species.

cxsmiles(mol)

mol as canonical CXSMILES without coordinates, its R-group atoms as $_R1$.

derive_generics(document, scene, labels, ...)

The drawing's R-group cores, bracketed groups and R-group definitions.

generics_report(document)

The document's generic structures and R-group definitions, as JSON data.

Exceptions

CapRefused

A labelled structure that cannot be capped as asked; the message says why.
exception vibesketch.document.generics.CapRefused[source]

Bases: ValueError

A labelled structure that cannot be capped as asked; the message says why.

vibesketch.document.generics.attachment_labels(mol)[source]

The labels of a structure’s attachment atoms (CNT, Au, …), in atom order (#139).

Parameters:

mol (Any)

Return type:

list[str]

vibesketch.document.generics.cap_labelled(document, generic_id, cap)[source]

document with a species made by capping a labelled structure, and that species.

Every attachment atom of the labelled generic structure generic_id (CNT, Au, …) is replaced by cap, H or CH3: the organic part as a molecule a calculation can take, which the user asked for by choosing the cap. The species records the generic structure, its labels and the cap. Raises CapRefused.

Parameters:
Return type:

tuple[Document, Species]

vibesketch.document.generics.cxsmiles(mol)[source]

mol as canonical CXSMILES without coordinates, its R-group atoms as $_R1$.

Parameters:

mol (Any)

Return type:

str

vibesketch.document.generics.derive_generics(document, scene, labels, taken, warnings)[source]

The drawing’s R-group cores, bracketed groups and R-group definitions.

Only what figures can draw becomes an entry; a structure the drawing cannot express stays a note, as before. A generic structure keeps its id and compound number while its CXSMILES is the same. taken holds the identifiers already used, and gains the new ones.

Parameters:
Return type:

tuple[list[Generic], list[RGroup]]

vibesketch.document.generics.generics_report(document)[source]

The document’s generic structures and R-group definitions, as JSON data.

A labelled structure also lists the species capped from it (#139).

Parameters:

document (Document)

Return type:

dict[str, list[dict[str, Any]]]