vibesketcher.document.displacements¶
Carrying measured displacement tensors through structure edits (#199).
CIF import keeps anisotropic displacement tensors (_atom_site_aniso U, B
or beta) in provenance["displacement_parameters"], keyed by site ID and
stamped with the cell rows they refer to (cell_angstrom). Every edit that
derives a structure from such a parent either transforms the record or
refuses:
Relabelling, lattice translations, supercells and other re-expressions of the same crystal in the same Cartesian frame (primitive, conventional, standard, Niggli/Delaunay-reduced and setting-transformed cells) leave the Cartesian tensor of each atom unchanged; only the site keys are mapped through the new site map (
carry(),carry_by_position()).A rotation R of the Cartesian frame (a slab cut, a rigid rotation of selected sites) maps U_cart -> R U_cart R^T (R. W. Grosse-Kunstleve and P. D. Adams, J. Appl. Cryst. 35, 477 (2002), Section 2).
A strain or deformation of the periodic cell, symmetry idealisation of the metric, or a change of the element on a measured site is not a symmetry of the measurement: the tensors are not physically transferable, and the edit is refused (
refuse()) until the caller drops them explicitly withdrop(), which records the reason and the dropped record inprovenance["displacement_parameters_dropped"].
The model itself refuses a record whose site keys or cell no longer match the
structure (model._check_displacement_record), so an edit that copies the
record without passing through here fails instead of keeping stale tensors.
Functions
|
|
|
Carry the tensors onto a re-expression of the same crystal in the same frame. |
|
|
|
The document with |
|
|
|
The export-loss line for a writer that cannot carry the tensors, or None. |
|
Document structures with tensors that a recipe names anywhere in its fields. |
|
Raise when |
|
Writers without a tensor field fail closed instead of dropping the tensors. |
|
Refuse a derived structure that lost its parents' tensors without a record. |
|
child -> parent site IDs when |
|
The cell the record of |
|
(convention, {site: U_cart in angstrom^2}) of the recorded tensors, or None. |
- vibesketcher.document.displacements.has_tensors(structure)[source]¶
- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.displacements.tensors(structure)[source]¶
(convention, {site: U_cart in angstrom^2}) of the recorded tensors, or None.
- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.displacements.stamped(structure)[source]¶
The cell the record of
structurerefers to (its own lattice rows).- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.displacements.carry(parent, child, site_map, *, how, rotation=None, rotations=None)[source]¶
childwith the parent’s tensors mapped throughsite_map(child -> parent ID).rotationis the proper Cartesian rotation R (column vectors, x’ = R x) taking the parent’s frame to the child’s; U’ = R U R^T. Without it the frames coincide and U is copied.rotationsgives a rotation for single child sites instead (a rigid rotation of a selection). Child sites without a measured parent (added atoms) are listed asunmeasured_sites.- Parameters:
parent (PeriodicStructure)
child (PeriodicStructure)
how (str)
rotation (ndarray | None)
- Return type:
- vibesketcher.document.displacements.site_map_by_position(parent, child, *, tolerance=0.001, rotation=None, origin=None, translate=False)[source]¶
child -> parent site IDs when
childre-expresses the parent crystal, else None.Each child atom must coincide (within
toleranceangstrom, same element) with a parent atom or one of its lattice images after x -> R^T x - origin (translate=Truesearches the rigid origin shift), and each periodic child cell vector must be a translation of the parent crystal, which excludes any strain of the cell. Cartesian U is invariant under the translation.- Parameters:
parent (PeriodicStructure)
child (PeriodicStructure)
tolerance (float)
rotation (ndarray | None)
origin (ndarray | None)
translate (bool)
- Return type:
- vibesketcher.document.displacements.carry_by_position(parent, child, *, how, what, tolerance=0.001, translate=False)[source]¶
Carry the tensors onto a re-expression of the same crystal in the same frame.
The site map is found geometrically (
site_map_by_position()); a child that is not such a re-expression (a strained or idealised cell, moved atoms) is refused while the parent carries tensors.- Parameters:
parent (PeriodicStructure)
child (PeriodicStructure)
how (str)
what (str)
tolerance (float)
translate (bool)
- Return type:
- vibesketcher.document.displacements.refuse(parent, what)[source]¶
Raise when
parentcarries tensors thatwhatcannot transform.- Parameters:
parent (PeriodicStructure)
what (str)
- Return type:
None
- vibesketcher.document.displacements.loss(structure)[source]¶
The export-loss line for a writer that cannot carry the tensors, or None.
- Parameters:
structure (PeriodicStructure)
- Return type:
str | None
- vibesketcher.document.displacements.refuse_export(structure, writer)[source]¶
Writers without a tensor field fail closed instead of dropping the tensors.
- Parameters:
structure (PeriodicStructure)
writer (str)
- Return type:
None
- vibesketcher.document.displacements.require_carried(parents, child, what)[source]¶
Refuse a derived structure that lost its parents’ tensors without a record.
- Parameters:
parents (list[PeriodicStructure])
child (PeriodicStructure)
what (str)
- Return type:
- vibesketcher.document.displacements.drop(structure, reason)[source]¶
structurewithout its displacement tensors; the reason and record are kept.The dropped record is stored whole under
displacement_parameters_droppedso the drop is explicit and reviewable; later edits carry that marker.- Parameters:
structure (PeriodicStructure)
reason (str)
- Return type: