vibe-sketcherDocumentation

vibesketcher.render.periodic

Publication figures of periodic structures (#189).

A figure is drawn from the validated PeriodicStructure, never from a picture: atoms (with display repeats and optional boundary completion), bonds found from covalent radii across cell boundaries, the outline of the cell’s periodic edges, the lattice vectors with their lengths, a Miller plane, the real-space Wigner-Seitz cell and, in a separate panel, the first Brillouin zone of the reciprocal lattice with b_i . a_j = 2 pi delta_ij. Display repeats are drawing only; they never change the model.

The camera looks along a stated direction: top (along -z), side (along +y), front (along -x), isometric, a real-space direction [uvw] or the normal of a plane (hkl). Screen axes are right-handed (right x up = towards the viewer). Atom colours follow the Jmol scheme; radii are RDKit’s covalent radii (Cordero et al., Dalton Trans. 2832 (2008)).

Functions

camera(direction)

Screen right and up for a camera looking along direction.

periodic_figure(structure[, options, fmt, dpi])

SVG, or PDF/PNG through the publication extra.

periodic_figure_svg(structure[, options])

The figure as standalone SVG (UTF-8).

plane_polygon(structure, hkl)

Vertices (Cartesian) where the plane hx + ky + lz = 1 cuts the unit cell.

reciprocal_structure(structure)

The reciprocal lattice (rows b_i, 1/angstrom, b_i .

view_direction(structure, options)

The unit vector the camera looks along, in Cartesian angstrom space.

Classes

FigureOptions(*[, view, direction, repeat, ...])

What a periodic figure shows; every choice is stated, none inferred.

Exceptions

FigureRefused

The options ask for something this structure cannot show.
class vibesketcher.render.periodic.FigureOptions(*, view='top', direction=None, repeat=(1, 1, 1), complete_boundary=True, cell=True, vectors=True, bonds=True, labels='none', legend=True, scale_bar=True, plane=None, wigner_seitz=False, brillouin=False, heights=False, depth_cue=False, polyhedra=<factory>, layers=False, stacking=False, symmetry_elements=False, inplane_axes=False, symprec=0.001, atom_scale=0.45, width=520, title=None)[source]

Bases: BaseModel

What a periodic figure shows; every choice is stated, none inferred.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

view: View
direction: tuple[int, int, int] | None
repeat: tuple[int, int, int]
complete_boundary: bool
cell: bool
vectors: bool
bonds: bool
labels: Literal['none', 'element', 'site', 'wyckoff']
legend: bool
scale_bar: bool
plane: tuple[int, int, int] | None
wigner_seitz: bool
brillouin: bool
heights: bool

Schematic aids (#233); each is drawn from the unchanged 3D model. Heights of the atoms along the view, written beside them (atoms that coincide in projection share one label).

depth_cue: bool

Atoms further from the viewer drawn smaller and paler.

polyhedra: list[str]

Elements whose coordination polyhedra are drawn, e.g. [“Ti”].

layers: bool

Slab layers numbered from the bottom, fixed layers marked (side views).

stacking: bool

Stacking letters (A, B, C, …) of the atomic planes of a slab (side views).

symmetry_elements: bool

The space group’s symmetry elements in the projection, as in International Tables diagrams (views along a, b or c of a 3D crystal).

inplane_axes: bool

also the two-fold axes lying in the projection plane.

Type:

With symmetry_elements

symprec: float

Length tolerance (angstrom) when spglib finds the group or the Wyckoff letters.

atom_scale: float
width: float
title: str | None
exception vibesketcher.render.periodic.FigureRefused[source]

Bases: ValueError

The options ask for something this structure cannot show.

vibesketcher.render.periodic.view_direction(structure, options)[source]

The unit vector the camera looks along, in Cartesian angstrom space.

Parameters:
Return type:

ndarray

vibesketcher.render.periodic.camera(direction)[source]

Screen right and up for a camera looking along direction.

Parameters:

direction (ndarray)

Return type:

tuple[ndarray, ndarray]

vibesketcher.render.periodic.plane_polygon(structure, hkl)[source]

Vertices (Cartesian) where the plane hx + ky + lz = 1 cuts the unit cell.

Parameters:
Return type:

ndarray

vibesketcher.render.periodic.reciprocal_structure(structure)[source]

The reciprocal lattice (rows b_i, 1/angstrom, b_i . a_j = 2 pi delta_ij) as a cell.

Parameters:

structure (PeriodicStructure)

Return type:

PeriodicStructure

vibesketcher.render.periodic.periodic_figure_svg(structure, options=None)[source]

The figure as standalone SVG (UTF-8).

Parameters:
Return type:

bytes

vibesketcher.render.periodic.periodic_figure(structure, options=None, fmt='svg', *, dpi=300)[source]

SVG, or PDF/PNG through the publication extra.

Parameters:
Return type:

bytes