vibe-sketcherDocumentation

vibesketcher.chem.reticular

Reticular frameworks from drawn building blocks with explicit connection points (#202).

A building block is a molecule whose connection points are marked by dummy atoms: * in SMILES ([*:1], [1*]), the R-group and attachment atoms of a drawn generic structure (_R1, _AP1), or X in an explicit atom list. Each marker is bonded to exactly one anchor atom; the anchor-to-marker direction is the attachment direction. Markers are never physical atoms: they are removed before assembly, the anchors are bonded to their partners across a net edge, and the assembly record says how many markers were consumed.

The net is chosen explicitly from a small catalogue defined here from the geometry of the lattice itself (simple cubic, diamond, square and honeycomb graphs; vertex and edge lists written out by hand). Their three-letter names follow the RCSR convention (O’Keeffe, Peskov, Ramsden and Yaghi, Acc. Chem. Res. 41, 1782 (2008), doi:10.1021/ar800124u); no RCSR or PORMAKE data is bundled or read. Construction is the reticular one (Yaghi, O’Keeffe, Ockwig, Chae, Eddaoudi and Kim, Nature 423, 705 (2003), doi:10.1038/nature01650): a node block on every vertex, a ditopic linker block on every edge, or the nodes joined directly when no linker is given.

Each node is rotated onto its vertex by the proper rotation that best maps its centre-to-marker directions onto the vertex’s edge directions over every assignment of markers to edges (W. Kabsch, Acta Cryst. A32, 922 (1976), doi:10.1107/S0567739476001873; ties keep the first assignment in lexicographic order). A linker’s anchor-to-anchor axis is laid along its edge and its widest perpendicular direction along a fixed reference turned by linker_rotation. The edge length is the longest one any edge needs for bonds of the covalent-radius sum (Cordero et al., Dalton Trans. 2008, 2832, doi:10.1039/b801115j). Blocks drawn without coordinates are embedded with RDKit’s ETKDG v3 and MMFF94 (or UFF) under a fixed seed, markers standing in as hydrogen. Nothing is relaxed: the coordinates are an unrelaxed starting geometry, and misfits are reported (or refused), never smoothed away.

Interpenetration, rod nodes, merged nets, partitioned pores and supertetrahedral units are gated extensions, refused by name.

Module Attributes

ASSEMBLY_VERSION

Version of this construction, recorded in provenance.

MAX_MARKERS

Connection points one block may carry.

MAX_BLOCK_ATOMS

Explicit atoms one block may list.

GATED_EXTENSIONS

Extensions a topology name does not imply; each is refused until designed.

Functions

assembly_refusals(structure)

Why a writer must not export this structure's atoms; empty when it may.

build_reticular(recipe[, document])

Assemble the framework; refuse (AssemblyRefused) what cannot close cleanly.

net_catalog()

The nets and gated extensions, for clients that present choices.

preview(recipe[, document])

Build without storing: the structure and its assembly record, or the refusal.

Classes

BlockAtom(*, symbol, xyz)

One explicit atom; X marks a connection point.

BlockSpec(*[, smiles, generic, atoms, bonds])

A building block: SMILES, a drawn generic structure, or explicit atoms.

Net(name, description, dimension, lattice, ...)

A periodic net with unit edge length; rows of lattice are cell vectors.

NetEdge(id, tail, head, image)

From vertex tail in the home cell to vertex head in cell image.

ReticularRecipe(*[, kind, second_node, ...])

A framework from a node block, an optional linker block and an explicit net.

Exceptions

AssemblyRefused(code, message)

A reticular assembly the builder will not produce; code is stable.

vibesketcher.chem.reticular.GATED_EXTENSIONS = ('interpenetration', 'rod_nodes', 'merged_nets', 'partitioned_pores', 'supertetrahedral_units')

Extensions a topology name does not imply; each is refused until designed.

exception vibesketcher.chem.reticular.AssemblyRefused(code, message)[source]

Bases: BuildRefused

A reticular assembly the builder will not produce; code is stable.

Parameters:
Return type:

None

class vibesketcher.chem.reticular.BlockSpec(*, smiles=None, generic=None, atoms=<factory>, bonds=<factory>)[source]

Bases: _Spec

A building block: SMILES, a drawn generic structure, or explicit atoms.

Parameters:
smiles: str | None
generic: str | None
atoms: list[BlockAtom]
bonds: list[tuple[int, int, float]]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketcher.chem.reticular.ReticularRecipe(*, kind='reticular', identifier, net, node, second_node=None, linker=None, linker_rotation=0.0, angle_tolerance=20.0, closure_tolerance=0.3, min_distance=1.0, vacuum=15.0, interpenetration=1, extensions=<factory>)[source]

Bases: _Spec

A framework from a node block, an optional linker block and an explicit net.

Parameters:
  • kind (Literal['reticular'])

  • identifier (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • net (Annotated[str, MinLen(min_length=1), MaxLen(max_length=32)])

  • node (BlockSpec)

  • second_node (BlockSpec | None)

  • linker (BlockSpec | None)

  • linker_rotation (Annotated[float, Ge(ge=-360), Le(le=360), AllowInfNan(allow_inf_nan=False)])

  • angle_tolerance (Annotated[float, Gt(gt=0), Le(le=60), AllowInfNan(allow_inf_nan=False)])

  • closure_tolerance (Annotated[float, Gt(gt=0), Le(le=2), AllowInfNan(allow_inf_nan=False)])

  • min_distance (Annotated[float, Gt(gt=0), Le(le=3), AllowInfNan(allow_inf_nan=False)])

  • vacuum (Annotated[float, Ge(ge=5), Le(le=200), AllowInfNan(allow_inf_nan=False)])

  • interpenetration (Annotated[int, Ge(ge=1), Le(le=8)])

  • extensions (Annotated[list[str], MaxLen(max_length=8)])

kind: Literal['reticular']
identifier: _ID
net: str
node: BlockSpec
second_node: BlockSpec | None

A second node block for the second vertex of a two-vertex net (dia, hcb).

linker: BlockSpec | None

A ditopic linker on every edge; without one, node anchors bond directly.

linker_rotation: float
angle_tolerance: float
closure_tolerance: float
min_distance: float
vacuum: float
interpenetration: int
extensions: list[str]
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibesketcher.chem.reticular.assembly_refusals(structure)[source]

Why a writer must not export this structure’s atoms; empty when it may.

A reticular structure’s sites must hold no connection markers and leave no connection point unmapped. The record is checked rather than trusted to be absent: a structure that claims a reticular build without the record is refused too.

Parameters:

structure (PeriodicStructure)

Return type:

list[str]

vibesketcher.chem.reticular.build_reticular(recipe, document=None)[source]

Assemble the framework; refuse (AssemblyRefused) what cannot close cleanly.

Parameters:
Return type:

PeriodicStructure

vibesketcher.chem.reticular.net_catalog()[source]

The nets and gated extensions, for clients that present choices.

Return type:

dict[str, Any]

vibesketcher.chem.reticular.preview(recipe, document=None)[source]

Build without storing: the structure and its assembly record, or the refusal.

Parameters:
Return type:

dict[str, Any]