vibe-sketcherDocumentation

vibesketcher.document.symmetry_ops

Adopting detected symmetry, enantiomorphs and subgroup descent (#199).

Three edits on fully ordered, non-magnetic 3-D crystals, each previewed first and recorded so it can be undone:

  • adopt() records the space group spglib detects at a stated length tolerance as the structure’s adopted symmetry. By default nothing moves (no snapping); the preview reports how far symmetrisation would move every atom and cell vector, which orbits merge or split against the previously recorded orbits, and sites near a special position at a looser diagnostic tolerance. idealize=True applies the symmetrisation explicitly: atom positions are projected onto the group (the Reynolds average over the operations) and the metric tensor is averaged, G’ = <R^T G R>, keeping the cell’s orientation (W. Kabsch, Acta Cryst. A32, 922 (1976)).

  • enantiomorph() inverts a chiral structure through the origin and transforms its group: (R, t) -> (R, -t). The 11 enantiomorphic pairs of space-group types (P3_1 21 <-> P3_2 21, …) change type; the other Sohncke groups keep theirs. Achiral structures, and structures that are achiral within the diagnostic tolerance (ambiguous handedness), are refused.

  • descend() re-describes a structure in a subgroup H of its group G given an explicit setting transformation (P, p) and H’s Hall symbol. Every operation of H must map the structure in the new basis onto itself, and spglib must detect each of them; the index, its translationengleiche and klassengleiche parts and the splitting of every Wyckoff orbit are reported. By Hermann’s theorem a maximal subgroup is either t or k, so a descent that is neither is refused; automatic enumeration of the maximal subgroups is a later stage and is refused.

Settings, subgroups and normalisers follow International Tables for Crystallography Vol. A (6th ed., 2016), Sections 1.5 (transformations of the coordinate system), 1.7 (subgroups; Hermann’s theorem) and 3.5 (Euclidean normalisers, enantiomorphic pairs).

Measured anisotropic displacement tensors, when a structure carries them in provenance["displacement_parameters"], are co-transformed: U_cart -> R_c U_cart R_c^T (R. W. Grosse-Kunstleve and P. D. Adams, J. Appl. Cryst. 35, 477 (2002)). A convention that cannot be converted, or a tensor that cannot be carried (e.g. equivalent atoms with and without one), is refused, never dropped.

Module Attributes

ENANTIOMORPHS

The 11 enantiomorphic pairs of space-group types (ITA Vol.

CONVENTIONS

Displacement-tensor conventions that can be converted to Cartesian U.

Functions

add_derived(document, derived)

adopt(structure, *[, symprec, idealize, ...])

The structure with the detected group recorded as adopted; same ID, undoable.

adopt_in_document(document, structure, **options)

descend(structure, *, transformation, ...[, ...])

The structure described in subgroup subgroup of its group in basis (a,b,c)P, origin p.

displacement_tensors(structure)

(convention, {site: U_cart}) of the structure's recorded tensors, or None.

enantiomorph(structure, *, identifier[, ...])

The mirror-image crystal (inversion through the origin) with its group transformed.

enumerate_maximal_subgroups(*_args, **_kwargs)

Refused: automatic enumeration of maximal subgroups is a later stage (#199).

from_cartesian(tensor, convention, lattice)

preview_adopt(structure, *[, symprec, ...])

What adopting the detected group would record and move; changes nothing.

preview_descend(structure, *, ...[, symprec])

preview_enantiomorph(structure, *[, ...])

The inverted structure's group and record, or a refusal (ValueError).

stamp(structure)

Record the derived structure's own digest so undo can refuse after later edits.

to_cartesian(tensor, convention, lattice)

U_cart (angstrom^2) of one tensor in convention for rows lattice.

undo(document, structure)

Undo the last adoption of structure, or remove an unchanged derived structure.

vibesketcher.document.symmetry_ops.ENANTIOMORPHS: dict[int, int] = {76: 78, 78: 76, 91: 95, 92: 96, 95: 91, 96: 92, 144: 145, 145: 144, 151: 153, 152: 154, 153: 151, 154: 152, 169: 170, 170: 169, 171: 172, 172: 171, 178: 179, 179: 178, 180: 181, 181: 180, 212: 213, 213: 212}

The 11 enantiomorphic pairs of space-group types (ITA Vol. A, Section 3.5).

vibesketcher.document.symmetry_ops.CONVENTIONS = ('U_cart', 'U_cif', 'B_cif', 'U_star', 'beta')

Displacement-tensor conventions that can be converted to Cartesian U.

vibesketcher.document.symmetry_ops.to_cartesian(tensor, convention, lattice)[source]

U_cart (angstrom^2) of one tensor in convention for rows lattice.

Parameters:
  • tensor (ndarray)

  • convention (str)

  • lattice (ndarray)

Return type:

ndarray

vibesketcher.document.symmetry_ops.from_cartesian(tensor, convention, lattice)[source]
Parameters:
  • tensor (ndarray)

  • convention (str)

  • lattice (ndarray)

Return type:

ndarray

vibesketcher.document.symmetry_ops.displacement_tensors(structure)[source]

(convention, {site: U_cart}) of the structure’s recorded tensors, or None.

Parameters:

structure (PeriodicStructure)

Return type:

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

vibesketcher.document.symmetry_ops.preview_adopt(structure, *, symprec=0.001, idealize=False, diagnostic_symprec=0.1)[source]

What adopting the detected group would record and move; changes nothing.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.symmetry_ops.adopt(structure, *, symprec=0.001, idealize=False, diagnostic_symprec=0.1, source_sha256=None)[source]

The structure with the detected group recorded as adopted; same ID, undoable.

Without idealize no coordinate changes. source_sha256 (from the preview) refuses the adoption when the structure changed since.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.symmetry_ops.preview_enantiomorph(structure, *, symprec=0.001, diagnostic_symprec=0.1)[source]

The inverted structure’s group and record, or a refusal (ValueError).

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.symmetry_ops.enantiomorph(structure, *, identifier, symprec=0.001, diagnostic_symprec=0.1)[source]

The mirror-image crystal (inversion through the origin) with its group transformed.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.symmetry_ops.enumerate_maximal_subgroups(*_args, **_kwargs)[source]

Refused: automatic enumeration of maximal subgroups is a later stage (#199).

Parameters:
Return type:

None

vibesketcher.document.symmetry_ops.descend(structure, *, transformation, subgroup, identifier, symprec=0.001)[source]

The structure described in subgroup subgroup of its group in basis (a,b,c)P, origin p.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.symmetry_ops.preview_descend(structure, *, transformation, subgroup, symprec=0.001)[source]
Parameters:
Return type:

dict[str, Any]

vibesketcher.document.symmetry_ops.adopt_in_document(document, structure, **options)[source]
Parameters:
Return type:

Document

vibesketcher.document.symmetry_ops.add_derived(document, derived)[source]
Parameters:
Return type:

Document

vibesketcher.document.symmetry_ops.undo(document, structure)[source]

Undo the last adoption of structure, or remove an unchanged derived structure.

Parameters:
Return type:

Document

vibesketcher.document.symmetry_ops.stamp(structure)[source]

Record the derived structure’s own digest so undo can refuse after later edits.

Parameters:

structure (PeriodicStructure)

Return type:

PeriodicStructure