vibe-sketcherDocumentation

vibesketcher.document.crystal

Bravais lattices, prototype crystals and cell choices for periodic structures.

Cells are right-handed row vectors in angstrom, as in PeriodicStructure. Conventional cells use the standard settings of the International Tables for Crystallography, Vol. A (2016); primitive cells use the transformations of W. Setyawan and S. Curtarolo, Comput. Mater. Sci. 49, 299 (2010), doi:10.1016/j.commatsci.2010.05.010. Wigner-Seitz faces are the Voronoi-relevant lattice vectors of J. H. Conway and N. J. A. Sloane, Sphere Packings, Lattices and Groups, ch. 21 (Springer, 1999): within each coset T + 2L, only the shortest pair +-T bounds the cell.

Every builder records its recipe in provenance["builder"]; the document schema is unchanged. A Wigner-Seitz cell is an atom placement of the same lattice, not a different lattice.

Module Attributes

BRAVAIS_3D

Pearson-style symbols.

Functions

build_crystal(bravais, parameters, sites, *, ...)

Expand Wyckoff sites (conventional fractional) into a physical cell.

cartesian(structure)

cell_from_parameters(a, b, c, alpha, beta, gamma)

Rows a1 along x, a2 in the xy plane (the IUCr standard orientation).

centring_vectors(bravais)

conventional_lattice(bravais, parameters)

dimensionality(bravais)

from_space_group(symbol, parameters, sites, ...)

Expand an asymmetric unit with the operations of a space-group setting (#199).

lattice_rows(structure)

parse_operation(text)

Parse a coordinate triplet such as -x+y,-x,z+1/2 (ITA notation).

pbc_of(bravais)

primitive_cell(structure, bravais, *, identifier)

Reduce a conventional cell of the given Bravais type to its primitive cell.

primitive_transform(bravais)

P with primitive rows = P @ conventional rows (Setyawan-Curtarolo 2010).

prototype(name, *, identifier[, cell, a, c, ...])

Build a library prototype, optionally with other lattice constants or elements.

prototypes()

The prototype library as plain data (for the CLI, REST and MCP).

wigner_seitz_cell(structure, *, identifier)

Move each site to its lattice image nearest the origin lattice point.

wigner_seitz_polyhedron(structure)

Vertices (angstrom) and faces of the Wigner-Seitz cell of the periodic lattice.

Classes

LatticeParameters(a[, b, c, alpha, beta, ...])

Conventional-cell parameters in angstrom and degrees.

Prototype(name, description, bravais, ...[, ...])

A crystal prototype: lattice type, default parameters and Wyckoff data.
vibesketcher.document.crystal.BRAVAIS_3D = ('aP', 'mP', 'mS', 'oP', 'oS', 'oI', 'oF', 'tP', 'tI', 'hR', 'hP', 'cP', 'cI', 'cF')

Pearson-style symbols. Three-dimensional lattices use the 14 Bravais types; plane lattices use the 5 two-dimensional types; the line lattice is l.

vibesketcher.document.crystal.dimensionality(bravais)[source]
Parameters:

bravais (str)

Return type:

int

class vibesketcher.document.crystal.LatticeParameters(a, b=None, c=None, alpha=None, beta=None, gamma=None, vacuum=20.0)[source]

Bases: object

Conventional-cell parameters in angstrom and degrees.

vacuum is the length of each nonperiodic vector of a plane or line lattice; it is part of the recorded model, never invented later.

Parameters:
a: float
b: float | None = None
c: float | None = None
alpha: float | None = None
beta: float | None = None
gamma: float | None = None
vacuum: float = 20.0
vibesketcher.document.crystal.cell_from_parameters(a, b, c, alpha, beta, gamma)[source]

Rows a1 along x, a2 in the xy plane (the IUCr standard orientation).

Parameters:
Return type:

ndarray

vibesketcher.document.crystal.conventional_lattice(bravais, parameters)[source]
Parameters:
Return type:

ndarray

vibesketcher.document.crystal.primitive_transform(bravais)[source]

P with primitive rows = P @ conventional rows (Setyawan-Curtarolo 2010).

Parameters:

bravais (str)

Return type:

ndarray

vibesketcher.document.crystal.centring_vectors(bravais)[source]
Parameters:

bravais (str)

Return type:

ndarray

vibesketcher.document.crystal.pbc_of(bravais)[source]
Parameters:

bravais (str)

Return type:

tuple[bool, bool, bool]

vibesketcher.document.crystal.parse_operation(text)[source]

Parse a coordinate triplet such as -x+y,-x,z+1/2 (ITA notation).

Parameters:

text (str)

Return type:

tuple[ndarray, ndarray]

class vibesketcher.document.crystal.Prototype(name, description, bravais, parameters, sites, operations=(), reference='', species=())[source]

Bases: object

A crystal prototype: lattice type, default parameters and Wyckoff data.

Parameters:
name: str
description: str
bravais: str
parameters: LatticeParameters
sites: tuple[tuple[str, tuple[float, float, float]], ...]
operations: tuple[str, ...] = ()
reference: str = ''
species: tuple[str, ...] = ()
vibesketcher.document.crystal.prototypes()[source]

The prototype library as plain data (for the CLI, REST and MCP).

Return type:

list[dict[str, Any]]

vibesketcher.document.crystal.build_crystal(bravais, parameters, sites, *, identifier, operations=(), cell='conventional', tolerance=0.0001, species_map=None, recipe=None)[source]

Expand Wyckoff sites (conventional fractional) into a physical cell.

operations are ITA coordinate triplets without the centring translations, which the Bravais type adds. Without operations the sites are taken as the full P1 motif of one lattice point. species_map renames elements of a prototype ({"Mg": "Ca"} turns MgO into CaO).

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.crystal.lattice_rows(structure)[source]
Parameters:

structure (PeriodicStructure)

Return type:

ndarray

vibesketcher.document.crystal.cartesian(structure)[source]
Parameters:

structure (PeriodicStructure)

Return type:

ndarray

vibesketcher.document.crystal.primitive_cell(structure, bravais, *, identifier, tolerance=0.0001, recipe=None)[source]

Reduce a conventional cell of the given Bravais type to its primitive cell.

The site count must drop by exactly the number of lattice points of the conventional cell, which proves that the motif carries the centring.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.crystal.prototype(name, *, identifier, cell='primitive', a=None, c=None, vacuum=None, species_map=None)[source]

Build a library prototype, optionally with other lattice constants or elements.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.crystal.wigner_seitz_cell(structure, *, identifier, tolerance=1e-06)[source]

Move each site to its lattice image nearest the origin lattice point.

The lattice, composition and site order are unchanged, so a PBC job sees the same model; a cyclic cluster takes its shape from this placement. Sites equidistant from two lattice points lie on a Wigner-Seitz face; the image with the lexicographically smallest translation is kept and the site is listed in provenance["builder"]["boundary_sites"].

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.crystal.wigner_seitz_polyhedron(structure)[source]

Vertices (angstrom) and faces of the Wigner-Seitz cell of the periodic lattice.

3-D lattices give a polyhedron with faces listed as vertex cycles, plane lattices a polygon in the periodic plane and the line lattice a segment. Faces are the Voronoi-relevant vectors (Conway and Sloane, ch. 21).

Parameters:

structure (PeriodicStructure)

Return type:

dict[str, Any]

vibesketcher.document.crystal.from_space_group(symbol, parameters, sites, *, identifier, cell='conventional', tolerance=0.0001, near_special=0.1, species_map=None)[source]

Expand an asymmetric unit with the operations of a space-group setting (#199).

sites are fractional coordinates of the setting’s conventional cell. Every generated site records its orbit (the asymmetric site it comes from) and the orbit’s multiplicity; a site that comes within near_special angstrom of a special position without lying on it is reported, never moved (no snapping). Two elements on one position are refused.

Parameters:
Return type:

PeriodicStructure