vibe-sketcherDocumentation

vibesketcher.document.periodic_prepare

Reviewable crystal preparation: previews of derived models with deltas (#200).

Each operation reads one periodic structure and proposes a derived model under a new ID, together with its site, stoichiometry, charge and edge deltas and the source digest it was computed from. Nothing is removed, ordered, protonated or repaired silently: an operation whose choice is ambiguous lists refusals with stable codes and cannot be applied until the request is narrowed.

Prepared means a reviewed starting model, not a validated electronic state or an equilibrium structure.

  • remove_duplicates drops sites of one element that coincide (minimum image within tolerance); coincident sites that are partially occupied, in a disorder group or of different elements are refused, not merged.

  • remove_fragments drops chosen 0-D fragments (guests, solvent) of the stored chemical graph; periodic fragments are refused, and a charged structure needs the removed fragments’ total charge.

  • complete_hydrogens adds hydrogen to carbon whose authored graph fixes the geometry (sp3 CH and CH2, sp2 CH, sp CH, from the bond-order sum and the neighbour directions; bond lengths 1.09, 1.08 and 1.06 A, an idealised tetrahedral H-C-H angle of 109.47 degrees). Protonation of heteroatoms is never guessed, and rotors (CH3, terminal =CH2), metal neighbours, non-integer (aromatic) order sums, disordered sites and unreviewed perceived bonds are refused.

Module Attributes

CODES

Stable refusal and notice codes of the preparation operations.

Functions

apply(document, preparation, *[, source_sha256])

Add the derived model to a copy of document; refusals and stale sources fail.

content_digest(structure)

Digest of a structure without its provenance (which records the digest).

parse_preparation(data)

preview(structure, preparation)

The derived model, its deltas, refusals and provenance; nothing is stored.

undo(document, identifier)

Remove a derived model again, if it is unchanged since it was prepared.

Classes

CompleteHydrogens(*[, operation, sites])

Preparation(*, source[, identifier])

RemoveDuplicates(*[, operation, tolerance])

RemoveFragments(*[, operation, fragments, ...])

vibesketcher.document.periodic_prepare.CODES: dict[str, str] = {'prepare.aromatic_ambiguous': 'a non-integer bond-order sum leaves the hydrogen count open', 'prepare.charge_unstated': 'the structure is charged; state the removed charge', 'prepare.coincident_elements': 'sites of different elements coincide', 'prepare.disordered_site': 'the site is partially occupied or disordered', 'prepare.duplicate_disordered': 'coincident sites are partially occupied or disordered', 'prepare.fragment_periodic': 'a chain, layer or framework cannot be removed as a guest', 'prepare.fragment_unknown': 'no fragment with that index or site', 'prepare.geometry_ambiguous': 'the neighbour directions do not fix the hydrogen direction', 'prepare.hydrogen_clash': 'a new hydrogen would sit too close to another atom', 'prepare.metal_coordination': 'metal neighbours leave the valence ambiguous', 'prepare.no_authored_graph': 'hydrogen completion reads the authored graph only', 'prepare.no_chemical_graph': 'the operation needs a stored chemical graph', 'prepare.no_duplicates': 'no coincident sites of one element', 'prepare.not_carbon': 'only carbon is completed; protonation is never guessed', 'prepare.nothing_to_add': 'every selected carbon is saturated', 'prepare.overvalent': 'the bond-order sum exceeds the valence', 'prepare.protonation_not_guessed': 'a heteroatom below its valence keeps its hydrogen count', 'prepare.removes_everything': 'the selection removes every site', 'prepare.rotor_ambiguous': 'the hydrogen positions need a torsion nobody chose', 'prepare.unreviewed_bonds': 'the site has perceived bonds nobody accepted'}

Stable refusal and notice codes of the preparation operations.

class vibesketcher.document.periodic_prepare.RemoveDuplicates(*, operation='remove_duplicates', tolerance=0.1)[source]

Bases: _Op

Parameters:
operation: Literal['remove_duplicates']
tolerance: float
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_prepare.RemoveFragments(*, operation='remove_fragments', fragments=<factory>, sites=<factory>, removed_charge=None)[source]

Bases: _Op

Parameters:
operation: Literal['remove_fragments']
fragments: list[int]

Fragment indices from the graph report.

sites: list[str]

each selects its whole fragment.

Type:

Or sites

removed_charge: int | None
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_prepare.CompleteHydrogens(*, operation='complete_hydrogens', sites=None)[source]

Bases: _Op

Parameters:
operation: Literal['complete_hydrogens']
sites: list[str] | None

Carbon sites to complete; every unsaturated carbon when omitted.

model_config = {'extra': 'forbid'}

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

class vibesketcher.document.periodic_prepare.Preparation(*, source, identifier=None, step)[source]

Bases: _Op

Parameters:
source: _ID
identifier: _ID | None
step: PrepareOp
model_config = {'extra': 'forbid'}

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

vibesketcher.document.periodic_prepare.parse_preparation(data)[source]
Parameters:

data (dict[str, Any])

Return type:

Preparation

vibesketcher.document.periodic_prepare.content_digest(structure)[source]

Digest of a structure without its provenance (which records the digest).

Parameters:

structure (PeriodicStructure)

Return type:

str

vibesketcher.document.periodic_prepare.preview(structure, preparation)[source]

The derived model, its deltas, refusals and provenance; nothing is stored.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.periodic_prepare.apply(document, preparation, *, source_sha256=None)[source]

Add the derived model to a copy of document; refusals and stale sources fail.

Parameters:
Return type:

Document

vibesketcher.document.periodic_prepare.undo(document, identifier)[source]

Remove a derived model again, if it is unchanged since it was prepared.

Parameters:
Return type:

Document