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
|
Version of this construction, recorded in provenance. |
|
Connection points one block may carry. |
|
Explicit atoms one block may list. |
Extensions a topology name does not imply; each is refused until designed. |
Functions
|
Why a writer must not export this structure's atoms; empty when it may. |
|
Assemble the framework; refuse ( |
The nets and gated extensions, for clients that present choices. |
|
|
Build without storing: the structure and its assembly record, or the refusal. |
Classes
|
One explicit atom; |
|
A building block: SMILES, a drawn generic structure, or explicit atoms. |
|
A periodic net with unit edge length; rows of |
|
From vertex |
|
A framework from a node block, an optional linker block and an explicit net. |
Exceptions
|
A reticular assembly the builder will not produce; |
- 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:
BuildRefusedA reticular assembly the builder will not produce;
codeis stable.
- class vibesketcher.chem.reticular.BlockSpec(*, smiles=None, generic=None, atoms=<factory>, bonds=<factory>)[source]¶
Bases:
_SpecA building block: SMILES, a drawn generic structure, or explicit atoms.
- Parameters:
- 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:
_SpecA 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)])
- kind: Literal['reticular']¶
- identifier: _ID¶
- second_node: BlockSpec | None¶
A second node block for the second vertex of a two-vertex net (dia, hcb).
- 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:
- vibesketcher.chem.reticular.build_reticular(recipe, document=None)[source]¶
Assemble the framework; refuse (
AssemblyRefused) what cannot close cleanly.- Parameters:
recipe (ReticularRecipe)
document (Document | None)
- Return type: