vibe-sketcherDocumentation

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

MAX_PAIRS

Pair results a neighbour search may return before it refuses.

MAX_CUTOFF

The largest neighbour cutoff (angstrom) the diagnostics accept.

MAX_UNDO_CHANGES

Graph edit records kept for undo; older records lose their inverse.

DEFAULT_SCALE

d <= scale * (r_a + r_b).

CLASH_FRACTION

Closer than this fraction of the radius sum (or 0.5 A) is a clash.

STRETCH_FRACTION

An authored bond longer than this fraction of the radius sum is stretched.

CODES

Every diagnostic code with its meaning; codes are stable API.

Functions

apply_graph_edit(structure, edit)

Apply the operations and record them with their inverse for undo_graph_edit().

chemical_edges(structure, *[, perceived])

Authored edges, plus stored perceived candidates unless perceived=False.

covalent_radius(symbol)

edge_key(a, b, image)

One key for an edge and its reverse (b to a in cell -image).

edge_vector(structure, a, b, image)

Cartesian vector from site a to site b in cell image (angstrom).

fragments(structure, edges)

Connected components of edges, each with its periodic dimensionality.

geometry_fingerprint(structure)

A digest of the cell, the sites' elements and positions (1e-6 resolution).

is_metal(symbol)

key_of(bond)

minimum_image(structure, a, b)

The image of b nearest to a and its distance (angstrom).

neighbours(structure, cutoff)

Every site pair (each once) closer than cutoff over all periodic images.

parse_graph_edit(data)

perceive(structure, *[, scale, metals, ...])

Perceived candidates d <= scale (r_a + r_b) not already stored as an edge.

report(structure)

Graph summary, fragments and diagnostics with stable codes and remedies.

undo_graph_edit(structure)

Revert the last recorded graph edit, refusing when its edges changed since.

unwrapped_offsets(structure, edges)

Image offsets that draw each 0-D fragment whole (the first site stays put).

Classes

AcceptPerceived(*[, op, edges])

AddBond(*[, op, image, order])

ClearPerceived(*[, op])

Diagnostic(code, severity, message, remedy, ...)

Fragment(sites, dimension, translations, ...)

GraphEdit(*, structure, operations)

Operations applied in order and recorded as one undoable step.

ImportCifDistances(*[, op, block, tolerance])

Pair(i, j, image, distance)

Perceive(*[, op, scale, metals, metal_metal])

RemoveBond(*[, op, image, kind])

SetOrder(*[, op, image])

Suppress(*[, op, image, reason])

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.is_metal(symbol)[source]
Parameters:

symbol (str)

Return type:

bool

vibesketcher.document.periodic_graph.covalent_radius(symbol)[source]
Parameters:

symbol (str)

Return type:

float

vibesketcher.document.periodic_graph.edge_key(a, b, image)[source]

One key for an edge and its reverse (b to a in cell -image).

Parameters:
Return type:

tuple[str, str, tuple[int, int, int]]

vibesketcher.document.periodic_graph.key_of(bond)[source]
Parameters:

bond (PeriodicBond)

Return type:

tuple[str, str, tuple[int, int, int]]

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:

str

class vibesketcher.document.periodic_graph.Pair(i: 'int', j: 'int', image: 'Image', distance: 'float')[source]

Bases: object

Parameters:
i: int
j: int
image: tuple[int, int, int]
distance: float
vibesketcher.document.periodic_graph.neighbours(structure, cutoff)[source]

Every site pair (each once) closer than cutoff over all periodic images.

Parameters:
Return type:

list[Pair]

vibesketcher.document.periodic_graph.edge_vector(structure, a, b, image)[source]

Cartesian vector from site a to site b in cell image (angstrom).

Parameters:
Return type:

ndarray

vibesketcher.document.periodic_graph.minimum_image(structure, a, b)[source]

The image of b nearest to a and its distance (angstrom).

Parameters:
Return type:

tuple[tuple[int, int, int], float]

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. With metals=False no pair involving a metal is proposed; metal-metal pairs are proposed only with metal_metal=True (radius sums of two metals reach the next coordination shell of most ionic solids).

Parameters:
Return type:

list[PeriodicBond]

class vibesketcher.document.periodic_graph.Fragment(sites: 'list[str]', dimension: 'int', translations: 'list[Image]', crosses_boundary: 'bool', formula: 'str')[source]

Bases: object

Parameters:
sites: list[str]
dimension: int
translations: list[tuple[int, int, int]]
crosses_boundary: bool
formula: str
as_json(index)[source]
Parameters:

index (int)

Return type:

dict[str, Any]

vibesketcher.document.periodic_graph.chemical_edges(structure, *, perceived=True)[source]

Authored edges, plus stored perceived candidates unless perceived=False.

Parameters:
Return type:

list[PeriodicBond]

vibesketcher.document.periodic_graph.fragments(structure, edges)[source]

Connected components of edges, each with its periodic dimensionality.

Parameters:
Return type:

list[Fragment]

vibesketcher.document.periodic_graph.unwrapped_offsets(structure, edges)[source]

Image offsets that draw each 0-D fragment whole (the first site stays put).

Parameters:
Return type:

dict[str, tuple[int, int, int]]

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:
code: str
severity: Literal['error', 'warning', 'info']
message: str
remedy: str
sites: list[str]
edges: list[list[Any]]
as_json()[source]
Return type:

dict[str, Any]

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:

dict[str, Any]

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
image: Image | None
order: float
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
order: float
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 (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

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

  • image (tuple[int, int, int])

  • kind (Literal['authored', 'perceived', 'distance', 'topology', 'suppressed'] | None)

op: Literal['remove_bond']
a: _ID
b: _ID
image: Image
kind: Literal['authored', 'perceived', 'distance', 'topology', 'suppressed'] | None
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 (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

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

  • image (tuple[int, int, int] | None)

  • reason (Annotated[str | None, MaxLen(max_length=200)])

op: Literal['suppress']
a: _ID
b: _ID
image: Image | None
reason: str | None
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']
scale: float
metals: bool
metal_metal: bool
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']
cif: str
block: str | None
tolerance: float
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: _Op

Operations applied in order and recorded as one undoable step.

Parameters:
structure: _ID
operations: list[GraphOp]
model_config = {'extra': 'forbid'}

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

vibesketcher.document.periodic_graph.parse_graph_edit(data)[source]
Parameters:

data (dict[str, Any])

Return type:

GraphEdit

vibesketcher.document.periodic_graph.apply_graph_edit(structure, edit)[source]

Apply the operations and record them with their inverse for undo_graph_edit().

Parameters:
Return type:

PeriodicStructure

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:

PeriodicStructure