vibe-sketcherDocumentation

vibesketcher.document.solid_build

Typed build recipes for periodic structures, shared by the SDK, CLI, REST and MCP.

A recipe names one construction step (crystal, cell choice, …) and its parameters; apply_recipe runs it against a document and returns the new structure. Recipes are recorded in the structure’s provenance, so the document schema does not change.

Functions

apply_recipe(document, recipe)

Run one recipe; the new identifier must not exist yet.

build(document, recipe)

Apply a recipe and add its structure to a copy of the document.

build_crystal(recipe)

cell_variant(recipe, source)

conventional_cell(structure, bravais, *, ...)

Expand a primitive cell to the conventional cell of its Bravais type.

parse_recipe(data)

Classes

AdsorbateRecipe(*[, kind, smiles, species, ...])

A molecule placed on a slab: from SMILES, a document species or explicit atoms.

AtomSpec(*, symbol, xyz)

CellRecipe(*[, kind, matrix, bravais, ...])

A cell choice of an existing structure: primitive, conventional, supercell, WS.

CrystalRecipe(*[, kind, prototype, ...])

A prototype from the library, or a Bravais type with parameters and a motif.

DefectRecipe(*[, kind, charge, multiplicity])

Vacancies, substitutions and interstitials with an explicit charge and spin (#191).

DefectSpec(*, kind[, site, symbol, fractional])

SiteSpec(*, symbol, fractional)

SlabRecipe(*[, kind, source, template, ...])

A slab cut from a 3-D bulk structure (#190).
class vibesketcher.document.solid_build.SiteSpec(*, symbol, fractional)[source]

Bases: _Recipe

Parameters:
symbol: str
fractional: 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_build.CrystalRecipe(*, kind='crystal', identifier, prototype=None, template=None, bravais=None, space_group=None, a=None, b=None, c=None, alpha=None, beta=None, gamma=None, vacuum=None, sites=<factory>, operations=<factory>, cell='primitive', species_map=<factory>)[source]

Bases: _Recipe

A prototype from the library, or a Bravais type with parameters and a motif.

Parameters:
kind: Literal['crystal']
identifier: _ID
prototype: str | None
template: str | None

A standard crystal from the template library, by name, alias or formula (#231).

bravais: str | None
space_group: str | int | None

A space group given by its ITA index, Hermann-Mauguin or Hall symbol, with :H, :R, :1 or :2 for the setting; sites are then its asymmetric unit (#199).

a: float | None
b: float | None
c: float | None
alpha: float | None
beta: float | None
gamma: float | None
vacuum: float | None
sites: list[SiteSpec]
operations: list[str]
cell: Literal['primitive', 'conventional']
species_map: dict[str, str]
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_build.CellRecipe(*, kind='cell', identifier, source, choice, matrix=None, bravais=None, symprec=0.001, idealize=False)[source]

Bases: _Recipe

A cell choice of an existing structure: primitive, conventional, supercell, WS.

Parameters:

  • kind (Literal['cell'])

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

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

  • choice (Literal['primitive', 'conventional', 'supercell', 'wigner_seitz', 'wigner_seitz_supercell', 'standard_conventional', 'standard_primitive', 'niggli', 'delaunay'])

  • matrix (list[list[int]] | None)

  • bravais (str | None)

  • symprec (Annotated[float, Gt(gt=0), Le(le=1)])

  • idealize (bool)

kind: Literal['cell']
identifier: _ID
source: _ID
choice: CellName
matrix: list[list[int]] | None
bravais: str | None
symprec: float

the length tolerance (angstrom) and whether to idealise positions.

Type:

Standard cells

idealize: bool
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_build.SlabRecipe(*, kind='slab', identifier, source=None, template=None, template_a=None, template_c=None, allow_polar=None, miller, layers, layer_unit='stoichiometric', termination=None, vacuum=15.0, repeat=<factory>, fixed_layers=0, periodicity='2d', surface_cell='primitive')[source]

Bases: _Recipe

A slab cut from a 3-D bulk structure (#190).

Parameters:
kind: Literal['slab']
identifier: _ID
source: _ID | None

The bulk structure in the document; or give template instead (#232).

template: str | None

A crystal template (see crystal_templates); the slab is cut from its conventional cell, so miller refers to that cell (hexagonal axes for R).

template_a: float | None
template_c: float | None
allow_polar: bool | None

Admit a slab with a formal-charge dipole or net charge (binary ionic crystals only); the default refuses polar slabs only when cut from a template.

miller: tuple[int, int, int]
layers: int
layer_unit: Literal['stoichiometric', 'plane', 'cell']
termination: int | None

The bottom plane; without it, 0, or for a template slab the first nonpolar termination where polarity is known.

vacuum: float
repeat: list[int] | list[list[int]]
fixed_layers: int
periodicity: Literal['2d', '3d']
surface_cell: Literal['primitive', 'given']
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_build.AtomSpec(*, symbol, xyz)[source]

Bases: _Recipe

Parameters:
symbol: str
xyz: 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_build.AdsorbateRecipe(*, kind='adsorbate', identifier, source, smiles=None, species=None, atoms=<factory>, site='top', anchor=None, position=None, height=2.5, orientation='flat', rotate=0.0, attach=None, min_distance=1.2)[source]

Bases: _Recipe

A molecule placed on a slab: from SMILES, a document species or explicit atoms.

Parameters:
kind: Literal['adsorbate']
identifier: _ID
source: _ID
smiles: str | None
species: str | None
atoms: list[AtomSpec]
site: Literal['top', 'bridge', 'hollow', 'position']
anchor: str | None
position: tuple[float, float] | None
height: float
orientation: Literal['flat', 'upright', 'as-is']
rotate: float
attach: int | None
min_distance: float
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_build.DefectSpec(*, kind, site=None, symbol=None, fractional=None)[source]

Bases: _Recipe

Parameters:
kind: Literal['vacancy', 'substitution', 'interstitial']
site: str | None
symbol: str | None
fractional: tuple[float, float, float] | None
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.solid_build.DefectRecipe(*, kind='defect', identifier, source, defects, charge=None, multiplicity=None)[source]

Bases: _Recipe

Vacancies, substitutions and interstitials with an explicit charge and spin (#191).

Parameters:

  • kind (Literal['defect'])

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

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

  • defects (Annotated[list[DefectSpec], MinLen(min_length=1), MaxLen(max_length=1000)])

  • charge (int | None)

  • multiplicity (Annotated[int | None, Ge(ge=1)])

kind: Literal['defect']
identifier: _ID
source: _ID
defects: list[DefectSpec]
charge: int | None
multiplicity: int | None
model_config = {'extra': 'forbid'}

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

vibesketcher.document.solid_build.build_crystal(recipe)[source]
Parameters:

recipe (CrystalRecipe)

Return type:

PeriodicStructure

vibesketcher.document.solid_build.conventional_cell(structure, bravais, *, identifier)[source]

Expand a primitive cell to the conventional cell of its Bravais type.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_build.cell_variant(recipe, source)[source]
Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_build.apply_recipe(document, recipe)[source]

Run one recipe; the new identifier must not exist yet.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.solid_build.build(document, recipe)[source]

Apply a recipe and add its structure to a copy of the document.

Parameters:
Return type:

Document

vibesketcher.document.solid_build.parse_recipe(data)[source]
Parameters:

data (dict[str, Any])

Return type:

CrystalRecipe | CellRecipe | SlabRecipe | AdsorbateRecipe | DefectRecipe | NanotubeRecipe | FrameworkRecipe | RolledNanotubeRecipe