vibesketcher.document.periodic_graph¶
Periodic chemical graphs: edge kinds, perception, diagnostics and edits (#200).
A periodic edge joins site a in the home cell to site b in the cell
displaced by the integer image: the labelled quotient graph of Chung, Hahn
and Klee (Acta Cryst. A40, 42 (1984), doi:10.1107/S0108767384000088). The edge
kind keeps apart what someone authored (the chemical graph), what a
distance rule perceived (candidates awaiting review), what a crystallographic
distance table lists, net/topology edges and pairs someone suppressed.
Nothing here runs implicitly. Geometry edits keep the stored edges as they are;
report() says when perceived edges predate the current geometry or an
authored bond is stretched, and a new perception only happens through an
explicit perceive operation, which records its rule and parameters.
Distances use covalent radii from RDKit’s table (Cordero et al., Dalton
Trans. 2008, 2832, doi:10.1039/b801115j). Neighbour search is a linked-cell
list (Allen and Tildesley, Computer Simulation of Liquids, section 5.3) over
the minimum images within the cutoff, bounded by MAX_PAIRS.
A fragment’s dimensionality is the rank of the lattice translations carried by
its cycles: walk the component assigning each site an image offset; an edge
closing a cycle contributes offset[a] + image - offset[b]. Rank 0 is a
molecule (possibly drawn across a cell face), 1 a chain, 2 a layer, 3 a net.
Module Attributes
Pair results a neighbour search may return before it refuses. |
|
The largest neighbour cutoff (angstrom) the diagnostics accept. |
|
Graph edit records kept for undo; older records lose their inverse. |
|
d <= scale * (r_a + r_b). |
|
Closer than this fraction of the radius sum (or 0.5 A) is a clash. |
|
An authored bond longer than this fraction of the radius sum is stretched. |
|
Every diagnostic code with its meaning; codes are stable API. |
Functions
|
Apply the operations and record them with their inverse for |
|
Authored edges, plus stored perceived candidates unless |
|
|
|
One key for an edge and its reverse ( |
|
Cartesian vector from site |
|
Connected components of |
|
A digest of the cell, the sites' elements and positions (1e-6 resolution). |
|
|
|
|
|
The image of |
|
Every site pair (each once) closer than |
|
|
|
Perceived candidates |
|
Graph summary, fragments and diagnostics with stable codes and remedies. |
|
Revert the last recorded graph edit, refusing when its edges changed since. |
|
Image offsets that draw each 0-D fragment whole (the first site stays put). |
Classes
|
|
|
|
|
|
|
|
|
|
|
Operations applied in order and recorded as one undoable step. |
|
|
|
|
|
|
|
|
|
|
|
- vibesketcher.document.periodic_graph.MAX_PAIRS = 2000000¶
Pair results a neighbour search may return before it refuses.
- vibesketcher.document.periodic_graph.MAX_CUTOFF = 8.0¶
The largest neighbour cutoff (angstrom) the diagnostics accept.
- vibesketcher.document.periodic_graph.MAX_UNDO_CHANGES = 50000¶
Graph edit records kept for undo; older records lose their inverse.
- vibesketcher.document.periodic_graph.DEFAULT_SCALE = 1.15¶
d <= scale * (r_a + r_b).
- Type:
Default perception rule
- vibesketcher.document.periodic_graph.CLASH_FRACTION = 0.6¶
Closer than this fraction of the radius sum (or 0.5 A) is a clash.
- vibesketcher.document.periodic_graph.STRETCH_FRACTION = 1.5¶
An authored bond longer than this fraction of the radius sum is stretched.
- vibesketcher.document.periodic_graph.edge_key(a, b, image)[source]¶
One key for an edge and its reverse (
btoain cell-image).
- vibesketcher.document.periodic_graph.geometry_fingerprint(structure)[source]¶
A digest of the cell, the sites’ elements and positions (1e-6 resolution).
- Parameters:
structure (PeriodicStructure)
- Return type:
- class vibesketcher.document.periodic_graph.Pair(i: 'int', j: 'int', image: 'Image', distance: 'float')[source]¶
Bases:
object
- vibesketcher.document.periodic_graph.neighbours(structure, cutoff)[source]¶
Every site pair (each once) closer than
cutoffover all periodic images.- Parameters:
structure (PeriodicStructure)
cutoff (float)
- Return type:
- vibesketcher.document.periodic_graph.edge_vector(structure, a, b, image)[source]¶
Cartesian vector from site
ato sitebin cellimage(angstrom).
- vibesketcher.document.periodic_graph.minimum_image(structure, a, b)[source]¶
The image of
bnearest toaand its distance (angstrom).
- vibesketcher.document.periodic_graph.perceive(structure, *, scale=1.15, metals=True, metal_metal=False)[source]¶
Perceived candidates
d <= scale (r_a + r_b)not already stored as an edge.Pairs stored as authored or suppressed edges are not proposed again; the candidates carry
kind="perceived", order 1 and the rule text. Withmetals=Falseno pair involving a metal is proposed; metal-metal pairs are proposed only withmetal_metal=True(radius sums of two metals reach the next coordination shell of most ionic solids).- Parameters:
structure (PeriodicStructure)
scale (float)
metals (bool)
metal_metal (bool)
- Return type:
- class vibesketcher.document.periodic_graph.Fragment(sites: 'list[str]', dimension: 'int', translations: 'list[Image]', crosses_boundary: 'bool', formula: 'str')[source]¶
Bases:
object- Parameters:
- vibesketcher.document.periodic_graph.chemical_edges(structure, *, perceived=True)[source]¶
Authored edges, plus stored perceived candidates unless
perceived=False.- Parameters:
structure (PeriodicStructure)
perceived (bool)
- Return type:
- vibesketcher.document.periodic_graph.fragments(structure, edges)[source]¶
Connected components of
edges, each with its periodic dimensionality.- Parameters:
structure (PeriodicStructure)
edges (list[PeriodicBond])
- Return type:
- vibesketcher.document.periodic_graph.unwrapped_offsets(structure, edges)[source]¶
Image offsets that draw each 0-D fragment whole (the first site stays put).
- Parameters:
structure (PeriodicStructure)
edges (list[PeriodicBond])
- Return type:
- class vibesketcher.document.periodic_graph.Diagnostic(code: 'str', severity: 'Severity', message: 'str', remedy: 'str', sites: 'list[str]' = <factory>, edges: 'list[list[Any]]' = <factory>)[source]¶
Bases:
object- Parameters:
- vibesketcher.document.periodic_graph.CODES: dict[str, str] = {'coordination.aromatic_ambiguous': 'aromatic (1.5) orders leave the Kekule structure open', 'coordination.isolated_site': 'a site has no chemical edge', 'coordination.metal_ambiguous': "a metal's coordination and valence stay a reviewer's call", 'coordination.overcoordinated': 'a light main-group atom has too many neighbours', 'coordination.valence_sum': "a light atom's bond-order sum differs from its valence", 'fragment.crosses_boundary': 'a molecule is drawn across a cell face', 'fragment.extended': 'a fragment is periodic (chain, layer or framework)', 'fragment.several': 'the cell holds more than one fragment', 'geometry.clash': 'two atoms (or an atom and an image) are far closer than a bond', 'geometry.duplicate_site': 'two sites of one element coincide', 'graph.bond_not_minimum_image': 'an authored bond joins an image farther than the nearest', 'graph.bond_stretched': 'an authored bond is much longer than a covalent bond', 'graph.distance_table_only': 'only crystallographic distance-table edges are stored', 'graph.duplicate_edge': 'an edge is stored twice', 'graph.missing_contact': 'a close pair has no authored, perceived or suppressed edge', 'graph.none': 'no chemical graph is stored', 'graph.perception_stale': 'the geometry changed after the perception', 'graph.perception_unrecorded': 'perceived edges carry no perception record', 'graph.self_edge': 'a site is bonded to itself in its own cell', 'graph.unreviewed_perceived': 'perceived candidates await review', 'site.partial_occupancy': 'a site is partially occupied or in a disorder group'}¶
Every diagnostic code with its meaning; codes are stable API.
- vibesketcher.document.periodic_graph.report(structure)[source]¶
Graph summary, fragments and diagnostics with stable codes and remedies.
- Parameters:
structure (PeriodicStructure)
- Return type:
- class vibesketcher.document.periodic_graph.AddBond(*, op='add_bond', a, b, image=None, order=1)[source]¶
Bases:
_Op- Parameters:
- op: Literal['add_bond']¶
- a: _ID¶
- b: _ID¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.SetOrder(*, op='set_order', a, b, image=(0, 0, 0), order)[source]¶
Bases:
_Op- Parameters:
- op: Literal['set_order']¶
- a: _ID¶
- b: _ID¶
- image: Image¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.RemoveBond(*, op='remove_bond', a, b, image=(0, 0, 0), kind=None)[source]¶
Bases:
_Op- Parameters:
- op: Literal['remove_bond']¶
- a: _ID¶
- b: _ID¶
- image: Image¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.Suppress(*, op='suppress', a, b, image=None, reason=None)[source]¶
Bases:
_Op- Parameters:
- op: Literal['suppress']¶
- a: _ID¶
- b: _ID¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.Perceive(*, op='perceive', scale=1.15, metals=True, metal_metal=False)[source]¶
Bases:
_Op- Parameters:
- op: Literal['perceive']¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.AcceptPerceived(*, op='accept_perceived', edges=None)[source]¶
Bases:
_Op- Parameters:
- op: Literal['accept_perceived']¶
- edges: list[tuple[str, str, Image]] | None¶
Edges to accept as
[a, b, image]; all perceived edges when omitted.
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.ClearPerceived(*, op='clear_perceived')[source]¶
Bases:
_Op- Parameters:
op (Literal['clear_perceived'])
- op: Literal['clear_perceived']¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.ImportCifDistances(*, op='import_cif_distances', cif, block=None, tolerance=0.02)[source]¶
Bases:
_Op- Parameters:
- op: Literal['import_cif_distances']¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.periodic_graph.GraphEdit(*, structure, operations)[source]¶
Bases:
_OpOperations applied in order and recorded as one undoable step.
- Parameters:
structure (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])
operations (Annotated[list[Annotated[AddBond | SetOrder | RemoveBond | Suppress | Perceive | AcceptPerceived | ClearPerceived | ImportCifDistances, FieldInfo(annotation=NoneType, required=True, discriminator='op')]], MinLen(min_length=1), MaxLen(max_length=1000)])
- structure: _ID¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- vibesketcher.document.periodic_graph.apply_graph_edit(structure, edit)[source]¶
Apply the operations and record them with their inverse for
undo_graph_edit().- Parameters:
structure (PeriodicStructure)
edit (GraphEdit)
- Return type:
- vibesketcher.document.periodic_graph.undo_graph_edit(structure)[source]¶
Revert the last recorded graph edit, refusing when its edges changed since.
- Parameters:
structure (PeriodicStructure)
- Return type: