vibe-sketcherDocumentation

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 with drop(), which records the reason and the dropped record in provenance["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(parent, child, site_map, *, how[, ...])

child with the parent's tensors mapped through site_map (child -> parent ID).

carry_by_position(parent, child, *, how, what)

Carry the tensors onto a re-expression of the same crystal in the same frame.

drop(structure, reason)

structure without its displacement tensors; the reason and record are kept.

drop_in_document(document, structure, reason)

The document with structure's tensors dropped for reason.

has_tensors(structure)

loss(structure)

The export-loss line for a writer that cannot carry the tensors, or None.

referenced(document, recipe)

Document structures with tensors that a recipe names anywhere in its fields.

refuse(parent, what)

Raise when parent carries tensors that what cannot transform.

refuse_export(structure, writer)

Writers without a tensor field fail closed instead of dropping the tensors.

require_carried(parents, child, what)

Refuse a derived structure that lost its parents' tensors without a record.

site_map_by_position(parent, child, *[, ...])

child -> parent site IDs when child re-expresses the parent crystal, else None.

stamped(structure)

The cell the record of structure refers to (its own lattice rows).

tensors(structure)

(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:

bool

vibesketcher.document.displacements.tensors(structure)[source]

(convention, {site: U_cart in angstrom^2}) of the recorded tensors, or None.

Parameters:

structure (PeriodicStructure)

Return type:

tuple[str, dict[str, ndarray]] | None

vibesketcher.document.displacements.stamped(structure)[source]

The cell the record of structure refers to (its own lattice rows).

Parameters:

structure (PeriodicStructure)

Return type:

dict[str, Any]

vibesketcher.document.displacements.carry(parent, child, site_map, *, how, rotation=None, rotations=None)[source]

child with the parent’s tensors mapped through site_map (child -> parent ID).

rotation is 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. rotations gives a rotation for single child sites instead (a rigid rotation of a selection). Child sites without a measured parent (added atoms) are listed as unmeasured_sites.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.displacements.site_map_by_position(parent, child, *, tolerance=0.001, rotation=None, origin=None, translate=False)[source]

child -> parent site IDs when child re-expresses the parent crystal, else None.

Each child atom must coincide (within tolerance angstrom, same element) with a parent atom or one of its lattice images after x -> R^T x - origin (translate=True searches 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:
Return type:

dict[str, str] | None

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:
Return type:

PeriodicStructure

vibesketcher.document.displacements.refuse(parent, what)[source]

Raise when parent carries tensors that what cannot transform.

Parameters:
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:
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:
Return type:

PeriodicStructure

vibesketcher.document.displacements.drop(structure, reason)[source]

structure without its displacement tensors; the reason and record are kept.

The dropped record is stored whole under displacement_parameters_dropped so the drop is explicit and reviewable; later edits carry that marker.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.displacements.drop_in_document(document, structure, reason)[source]

The document with structure’s tensors dropped for reason.

Parameters:
Return type:

Document

vibesketcher.document.displacements.referenced(document, recipe)[source]

Document structures with tensors that a recipe names anywhere in its fields.

Parameters:
Return type:

list[PeriodicStructure]