vibe-sketcherDocumentation

vibesketcher.document.slab

Slabs from a bulk cell and Miller index, and adsorbates placed on them.

The surface cell is a unimodular integer transform of the bulk cell whose first two rows span the (hkl) plane, following W. Sun and G. Ceder, Surf. Sci. 617, 53 (2013), doi:10.1016/j.susc.2013.05.016. Atoms are grouped into planes by height. A “layer” is either one atomic plane, one repeat of the oriented bulk cell, or the smallest run of planes whose composition is a multiple of the bulk formula (a stoichiometric layer, such as one Al-O3-Al unit of alpha-Al2O3(0001)). Polar or nonstoichiometric terminations are reported, never neutralised or passivated silently.

Functions

adsorb(slab, molecule, *, identifier[, ...])

Place a molecule above the top surface of a slab.

apply_defects(structure, defects, *, identifier)

Vacancies, substitutions and interstitials on named sites of a pristine structure.

build_slab(bulk, miller, *, identifier, layers)

Cut a slab of layers layers from a 3-D bulk structure.

formal_charges(structure)

Formal ionic charges of a binary compound, or None where they are not defined.

polarity(made, charges)

Net formal charge and dipole per area along the normal (e/Å) of a slab (Tasker 1979).

surface_transform(miller, lattice)

Integer rows (v1, v2, v3), det +1: v1 and v2 span (hkl), h .

terminations(bulk, miller, *[, layers, ...])

Every bottom termination of a cut, with what a slab from it would be (#232).
vibesketcher.document.slab.surface_transform(miller, lattice)[source]

Integer rows (v1, v2, v3), det +1: v1 and v2 span (hkl), h . v3 = 1.

Searches short integer vectors, so the in-plane cell is as compact as the bounded search allows; a Gauss reduction then makes it reduced.

Parameters:
Return type:

ndarray

vibesketcher.document.slab.build_slab(bulk, miller, *, identifier, layers, layer_unit='stoichiometric', termination=0, vacuum=15.0, repeat=(1, 1), fixed_layers=0, periodicity='2d', plane_tolerance=0.05, surface_cell='primitive')[source]

Cut a slab of layers layers from a 3-D bulk structure.

miller refers to the bulk structure’s own cell rows, so (0, 0, 1) of a hexagonal conventional corundum cell is the basal (0001) plane. termination selects the bottom plane among the distinct planes of one bulk repeat. vacuum (angstrom) is the gap between the slab and its image along the normal; periodicity="2d" gives a true 2-D model (PBC T, T, F), "3d" a vacuum-padded 3-D cell. The bottom fixed_layers layers are listed as fixed sites for optimisers. With surface_cell="primitive" a conventional cell of a centred lattice is first reduced to its primitive cell and the Miller index transformed with it, so the in-plane cell is the smallest surface cell of the crystal.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.slab.adsorb(slab, molecule, *, identifier, site='top', anchor=None, position=None, height=2.5, orientation='flat', rotate=0.0, attach=None, min_distance=1.2, label='adsorbate')[source]

Place a molecule above the top surface of a slab.

site names the reference point: top of the anchor surface atom (default: the top-most atom), the bridge between it and its nearest top-layer neighbour, the hollow centroid with its two nearest neighbours, or an explicit in-plane fractional position. height is the vertical distance (angstrom) of the molecule’s attach atom (default: its lowest atom after orientation) above that point’s surface height. flat puts the molecular plane parallel to the surface (benzene lying down), upright its long axis along the normal. Placements closer than min_distance to any slab atom or periodic image are refused.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.slab.apply_defects(structure, defects, *, identifier, charge=None, multiplicity=None)[source]

Vacancies, substitutions and interstitials on named sites of a pristine structure.

Each defect is {"kind": "vacancy", "site": id}, {"kind": "substitution", "site": id, "symbol": "Al"} or {"kind": "interstitial", "symbol": "H", "fractional": [x, y, z]}. The pristine structure, the defect map and the stoichiometric change are recorded; the charge and spin are what the caller states, never inferred.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.slab.formal_charges(structure)[source]

Formal ionic charges of a binary compound, or None where they are not defined.

The anion takes its standard charge and the cation the charge that makes the composition neutral. Elements, ternary and covalent (no tabulated anion) compounds give None: no polarity verdict is made for them.

Parameters:

structure (PeriodicStructure)

Return type:

dict[str, float] | None

vibesketcher.document.slab.polarity(made, charges)[source]

Net formal charge and dipole per area along the normal (e/Å) of a slab (Tasker 1979).

Parameters:
Return type:

dict[str, Any] | None

vibesketcher.document.slab.terminations(bulk, miller, *, layers=1, layer_unit='stoichiometric', surface_cell='primitive')[source]

Every bottom termination of a cut, with what a slab from it would be (#232).

Each entry gives the bottom and top plane compositions, whether the slab is stoichiometric and has equal terminations, its thickness and atom count, the builder’s warnings and, for binary ionic crystals, its formal-charge polarity (polarity()). Terminations that give the same slab (same compositions, thickness and atom count) point to the first one with same_as.

Parameters:
Return type:

list[dict[str, Any]]