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_duplicatesdrops sites of one element that coincide (minimum image withintolerance); coincident sites that are partially occupied, in a disorder group or of different elements are refused, not merged.remove_fragmentsdrops 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_hydrogensadds 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
Stable refusal and notice codes of the preparation operations. |
Functions
|
Add the derived model to a copy of |
|
Digest of a structure without its provenance (which records the digest). |
|
|
|
The derived model, its deltas, refusals and provenance; nothing is stored. |
|
Remove a derived model again, if it is unchanged since it was prepared. |
Classes
|
|
|
|
|
|
|
- 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']¶
- 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']¶
- 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']¶
- 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 (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])
identifier (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])] | None)
step (RemoveDuplicates | RemoveFragments | CompleteHydrogens)
- source: _ID¶
- step: PrepareOp¶
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- vibesketcher.document.periodic_prepare.content_digest(structure)[source]¶
Digest of a structure without its provenance (which records the digest).
- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.periodic_prepare.preview(structure, preparation)[source]¶
The derived model, its deltas, refusals and provenance; nothing is stored.
- Parameters:
structure (PeriodicStructure)
preparation (Preparation)
- Return type:
- 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:
document (Document)
preparation (Preparation)
source_sha256 (str | None)
- Return type: