vibe-sketcherDocumentation

vibesketcher.document.wyckoff

Wyckoff positions of the space-group settings (#229).

A Wyckoff position is a class of points whose site-symmetry groups are conjugate in the space group; its multiplicity is the number of points of one orbit in the conventional cell, the order of G over that of the site group (International Tables for Crystallography, Vol. A, sections 1.4.4 and 2.1.3.11). The letters (a for the most special position, the general position last, and A for the 27th position of P m m m, which the Tables write as alpha), the oriented site-symmetry symbols and the first coordinate triplet of each position come from data/wyckoff_positions.json, generated from spglib’s database by scripts/generate_wyckoff_table.py.

Nothing here trusts the table. check_setting() recomputes the site-symmetry orbits from the setting’s operations (spacegroups): every multiplicity must equal the orbit size of a generic point on its triplet, and every point of a 1/24 grid of the cell (which holds every fixed special position) must belong to exactly one listed position. A point p lies on the representative of a position with triplet x -> R x + t when R g p + t - g p is a lattice vector for some operation g and its site group has the position’s order, the test spglib uses (A. Togo, K. Shinohara and I. Tanaka, Sci. Technol. Adv. Mater. Meth. 4, 2384822 (2024)).

Module Attributes

LETTERS

Position letters in the order of the International Tables (A stands for alpha).

Functions

analyse_sites(symbol, sites[, tolerance])

Each site's Wyckoff position, free parameters and orbit, for previews (#229).

check_setting(symbol)

Problems found when the table is compared with the computed orbits (empty: none).

describe(symbol)

A setting and its Wyckoff positions, for the SDK, CLI, REST and MCP.

free_cell_parameters(symbol)

The lattice parameters a crystal of this setting takes; the system fixes the rest.

has_positions(symbol)

identify(symbol, point[, tolerance])

The Wyckoff position of a point and its free parameters on the representative.

normalise_triplet(text)

A triplet's (R, t) with t reduced to [0, 1): equal keys name the same points.

orbit(symbol, point[, tolerance])

The distinct images of a point in the conventional cell, wrapped into [0, 1).

orbit_triplets(symbol, triplet)

The symbolic orbit of a coordinate triplet under every operation (with centring).

parse_triplet(text)

"x,2x,1/4" as the affine map (R, t) of the free coordinates x, y, z.

position(symbol, letter)

A position by letter, c, or by multiplicity and letter, 12c.

positions(symbol)

The Wyckoff positions of a setting, from a to the general position.

reset_cache()

Forget the loaded table (the generator rewrites it).

site(symbol, letter[, values])

Fractional coordinates of a Wyckoff site, e.g. site("R-3c", "12c", {"z": 0.352}).

Classes

WyckoffPosition(letter, multiplicity, ...)

One Wyckoff position of a setting: 12c with site symmetry 3. at 0,0,z.

vibesketcher.document.wyckoff.LETTERS = 'abcdefghijklmnopqrstuvwxyzA'

Position letters in the order of the International Tables (A stands for alpha).

vibesketcher.document.wyckoff.parse_triplet(text)[source]

"x,2x,1/4" as the affine map (R, t) of the free coordinates x, y, z.

Parameters:

text (str)

Return type:

tuple[tuple[tuple[int, int, int], tuple[int, int, int], tuple[int, int, int]], tuple[Fraction, Fraction, Fraction]]

vibesketcher.document.wyckoff.normalise_triplet(text)[source]

A triplet’s (R, t) with t reduced to [0, 1): equal keys name the same points.

Parameters:

text (str)

Return type:

tuple[tuple[tuple[int, int, int], tuple[int, int, int], tuple[int, int, int]], tuple[Fraction, Fraction, Fraction]]

class vibesketcher.document.wyckoff.WyckoffPosition(letter, multiplicity, site_symmetry, triplet)[source]

Bases: object

One Wyckoff position of a setting: 12c with site symmetry 3. at 0,0,z.

Parameters:
  • letter (str)

  • multiplicity (int)

  • site_symmetry (str)

  • triplet (str)

letter: str
multiplicity: int
site_symmetry: str
triplet: str
property label: str[source]
property affine: tuple[tuple[tuple[int, int, int], tuple[int, int, int], tuple[int, int, int]], tuple[Fraction, Fraction, Fraction]][source]
property free: tuple[str, ...][source]

The free parameters, in x, y, z order (empty for a fixed position).

coordinate(values=None)[source]

The representative point for the given free parameters (every one required).

Parameters:

values (dict[str, float] | None)

Return type:

tuple[float, float, float]

describe()[source]
Return type:

dict[str, Any]

vibesketcher.document.wyckoff.reset_cache()[source]

Forget the loaded table (the generator rewrites it).

Return type:

None

vibesketcher.document.wyckoff.has_positions(symbol)[source]
Parameters:

symbol (str | int | Setting)

Return type:

bool

vibesketcher.document.wyckoff.positions(symbol)[source]

The Wyckoff positions of a setting, from a to the general position.

Parameters:

symbol (str | int | Setting)

Return type:

list[WyckoffPosition]

vibesketcher.document.wyckoff.position(symbol, letter)[source]

A position by letter, c, or by multiplicity and letter, 12c.

Parameters:
Return type:

WyckoffPosition

vibesketcher.document.wyckoff.site(symbol, letter, values=None)[source]

Fractional coordinates of a Wyckoff site, e.g. site("R-3c", "12c", {"z": 0.352}).

Parameters:
Return type:

tuple[float, float, float]

vibesketcher.document.wyckoff.orbit(symbol, point, tolerance=0.0001)[source]

The distinct images of a point in the conventional cell, wrapped into [0, 1).

Parameters:
Return type:

list[tuple[float, float, float]]

vibesketcher.document.wyckoff.orbit_triplets(symbol, triplet)[source]

The symbolic orbit of a coordinate triplet under every operation (with centring).

Parameters:
Return type:

set[tuple[tuple[tuple[int, int, int], tuple[int, int, int], tuple[int, int, int]], tuple[Fraction, Fraction, Fraction]]]

vibesketcher.document.wyckoff.identify(symbol, point, tolerance=0.0001)[source]

The Wyckoff position of a point and its free parameters on the representative.

tolerance is in fractional coordinates. The parameters are those of the first orbit image that lies on the position’s coordinate triplet.

Parameters:
Return type:

tuple[WyckoffPosition, dict[str, float]]

vibesketcher.document.wyckoff.free_cell_parameters(symbol)[source]

The lattice parameters a crystal of this setting takes; the system fixes the rest.

Parameters:

symbol (str | int | Setting)

Return type:

list[str]

vibesketcher.document.wyckoff.describe(symbol)[source]

A setting and its Wyckoff positions, for the SDK, CLI, REST and MCP.

Parameters:

symbol (str | int | Setting)

Return type:

dict[str, Any]

vibesketcher.document.wyckoff.check_setting(symbol)[source]

Problems found when the table is compared with the computed orbits (empty: none).

Exact integer arithmetic on the 1/24 grid: operations and triplets are scaled by 24, so every comparison is modulo 24.

Parameters:

symbol (str | int | Setting)

Return type:

list[str]

vibesketcher.document.wyckoff.analyse_sites(symbol, sites, tolerance=0.0001)[source]

Each site’s Wyckoff position, free parameters and orbit, for previews (#229).

A site is {"position": "12c", "parameters": {"z": 0.35}} or {"fractional": [x, y, z]}; element is carried through.

Parameters:
Return type:

dict[str, Any]