vibe-sketcherDocumentation

vibesketcher.document.solid_edit

Editing periodic structures: cell parameters, selected sites and slab layers.

Every edit returns a new validated PeriodicStructure and appends a record to provenance["builder"]["edits"]; by default the edited structure replaces its source under the same ID. Cell parameters follow the IUCr convention (a, b, c in angstrom, alpha = angle(b, c), beta = angle(a, c), gamma = angle(a, b) in degrees). The cell keeps its orientation: the new rows are the standard rows of the new parameters carried by the same rotation that maps the old standard rows onto the old cell.

Functions

add_slab_layers(document, structure, count, *)

Add count layers on top of a builder slab, under any adsorbates.

apply_edit(document, recipe)

Run one edit; without identifier the result replaces its source.

cell_parameters(structure)

a, b, c (angstrom), alpha, beta, gamma (degrees) and the volume.

edit(document, recipe)

Apply an edit and put its structure into a copy of the document.

edit_cell(structure, *[, identifier, a, b, ...])

Change lattice lengths and angles, scale the cell, or set a slab's vacuum.

move_sites(structure, sites, translation, *)

Translate the selected sites by a vector (angstrom, or fractions of the cell).

parse_edit(data)

rotate_sites(structure, sites, angle, *[, ...])

Rotate the selected sites by angle degrees about an axis through a point.

select_sites(structure, *[, sites, ...])

Site IDs matching every given criterion (all sites when none is given).

set_sites(structure, edits, *[, identifier])

Set positions (fractional or cartesian) and/or elements of named sites.

Classes

AddLayersRecipe(*[, kind, identifier])

EditCellRecipe(*[, kind, identifier, a, b, ...])

MoveSitesRecipe(*[, kind, identifier, ...])

Selection(*[, sites, elements, layers, ...])

SetSitesRecipe(*[, kind, identifier])

vibesketcher.document.solid_edit.cell_parameters(structure)[source]

a, b, c (angstrom), alpha, beta, gamma (degrees) and the volume.

Parameters:

structure (PeriodicStructure)

Return type:

dict[str, float]

vibesketcher.document.solid_edit.edit_cell(structure, *, identifier=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, scale=None, vacuum=None, keep='fractional')[source]

Change lattice lengths and angles, scale the cell, or set a slab’s vacuum.

keep="fractional" moves the atoms with the cell (strain); "cartesian" leaves them in place. Along a nonperiodic direction atoms always keep their physical distance from the middle of that vector, so a layer is never stretched by a vacuum change. vacuum sets the gap between a 2-D slab’s top and its image along the normal.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_edit.select_sites(structure, *, sites=None, elements=None, layers=None, adsorbate=None, z_min=None, z_max=None)[source]

Site IDs matching every given criterion (all sites when none is given).

layers uses the slab builder’s layer numbers (0 is the bottom); adsorbate an index or label of a recorded adsorbate; z_min/z_max Cartesian heights in angstrom.

Parameters:
Return type:

list[str]

vibesketcher.document.solid_edit.move_sites(structure, sites, translation, *, frame='cartesian', identifier=None)[source]

Translate the selected sites by a vector (angstrom, or fractions of the cell).

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_edit.rotate_sites(structure, sites, angle, *, axis=(0.0, 0.0, 1.0), centre=None, identifier=None)[source]

Rotate the selected sites by angle degrees about an axis through a point.

The default axis is z (the slab normal for builder slabs) through the selection’s centroid (Rodrigues’ rotation formula).

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_edit.set_sites(structure, edits, *, identifier=None)[source]

Set positions (fractional or cartesian) and/or elements of named sites.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_edit.add_slab_layers(document, structure, count, *, identifier=None)[source]

Add count layers on top of a builder slab, under any adsorbates.

The slab is cut again from its recorded bulk source with the same Miller index, layer unit, termination and repeat; the existing sites, including any moved or edited ones, stay where they are, the new layers’ atoms are added above the old top layer, adsorbate atoms move up with the surface and the normal vector grows by the added thickness.

Parameters:
Return type:

PeriodicStructure

class vibesketcher.document.solid_edit.EditCellRecipe(*, kind='edit_cell', source, identifier=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, scale=None, vacuum=None, keep='fractional')[source]

Bases: _Edit

Parameters:

  • kind (Literal['edit_cell'])

  • source (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • identifier (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])] | None)

  • a (float | None)

  • b (float | None)

  • c (float | None)

  • alpha (float | None)

  • beta (float | None)

  • gamma (float | None)

  • scale (float | None)

  • vacuum (float | None)

  • keep (Literal['fractional', 'cartesian'])

kind: Literal['edit_cell']
source: _ID
identifier: _ID | None
a: float | None
b: float | None
c: float | None
alpha: float | None
beta: float | None
gamma: float | None
scale: float | None
vacuum: float | None
keep: Keep
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_edit.Selection(*, sites=None, elements=None, layers=None, adsorbate=None, z_min=None, z_max=None)[source]

Bases: _Edit

Parameters:
sites: list[str] | None
elements: list[str] | None
layers: list[int] | None
adsorbate: int | str | None
z_min: float | None
z_max: float | None
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_edit.MoveSitesRecipe(*, kind='move_sites', source, identifier=None, select, translation=(0.0, 0.0, 0.0), frame='cartesian', rotate=None, axis=(0.0, 0.0, 1.0))[source]

Bases: _Edit

Parameters:
kind: Literal['move_sites']
source: _ID
identifier: _ID | None
select: Selection
translation: tuple[float, float, float]
frame: Literal['cartesian', 'fractional']
rotate: float | None
axis: tuple[float, float, float]
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_edit.SetSitesRecipe(*, kind='set_sites', source, identifier=None, sites)[source]

Bases: _Edit

Parameters:

  • kind (Literal['set_sites'])

  • source (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • identifier (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])] | None)

  • sites (Annotated[list[dict[str, Any]], MinLen(min_length=1), MaxLen(max_length=25000)])

kind: Literal['set_sites']
source: _ID
identifier: _ID | None
sites: list[dict[str, Any]]
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_edit.AddLayersRecipe(*, kind='add_layers', source, identifier=None, count)[source]

Bases: _Edit

Parameters:

  • kind (Literal['add_layers'])

  • source (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])

  • identifier (Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[A-Za-z][A-Za-z0-9_-]{0,63}$')])] | None)

  • count (Annotated[int, Ge(ge=1), Le(le=100)])

kind: Literal['add_layers']
source: _ID
identifier: _ID | None
count: int
model_config = {'extra': 'forbid'}

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

vibesketcher.document.solid_edit.apply_edit(document, recipe)[source]

Run one edit; without identifier the result replaces its source.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_edit.parse_edit(data)[source]
Parameters:

data (dict[str, Any])

Return type:

EditCellRecipe | MoveSitesRecipe | SetSitesRecipe | AddLayersRecipe

vibesketcher.document.solid_edit.edit(document, recipe)[source]

Apply an edit and put its structure into a copy of the document.

Parameters:
Return type:

Document