vibe-sketcherDocumentation

vibesketcher.chem.layered_carbon

Honeycomb layers: binary sheets, stacked multilayers and twisted bilayers (#201).

A honeycomb layer has the hexagonal lattice a1 = a (1, 0), a2 = a (1/2, sqrt(3)/2) (60 degrees apart) with sublattice A at the lattice points and sublattice B at A + (a1 + a2) / 3, so the A-B distance is a / sqrt(3). Graphene puts carbon on both sublattices (a = 2.46 angstrom); hexagonal boron nitride puts boron on A and nitrogen on B (a = 2.504 angstrom); a custom layer names both elements and a.

Stacks

Layer k (0-based) of a stack is shifted in-plane by s_k (a1 + a2) / 3: AA has s_k = 0 (eclipsed), AB (Bernal) s_k = k mod 2, ABC (rhombohedral) s_k = k mod 3, so A of layer k + 1 sits over B of layer k. AA’ is eclipsed with the sublattice chemistry swapped on every other layer (B over N, the h-BN bulk stacking). A periodic (3-D) stack repeats along c = L d and needs a whole number of stacking periods; a 2-D stack carries a stated vacuum.

Commensurate twisted bilayers

The construction of Lopes dos Santos, Peres and Castro Neto, Phys. Rev. Lett. 99, 256802 (2007) (also Shallcross, Sharma, Kandelaki and Pankratov, Phys. Rev. B 81, 165105, 2010): for coprime integers (m, r) the top layer is the bottom layer turned by theta about a common site, with

cos(theta) = (3m^2 + 3mr + r^2/2) / (3m^2 + 3mr + r^2),

and the superlattice is t1 = m a1 + (m + r) a2, t2 = -(m + r) a1 + (2m + r) a2 holding N = 4 (3m^2 + 3mr + r^2) atoms; when 3 divides r it is t1 = (m + r/3) a1 + (r/3) a2, t2 = -(r/3) a1 + (m + 2r/3) a2 with N = 4 (m^2 + mr + r^2/3). Both layers’ integer matrices are recorded and checked: t1 and t2 must be lattice vectors of the turned layer to 1e-9. A requested angle is matched to such a cell only when it agrees within the stated tolerance; any other angle is refused with the nearest commensurate cells, never rounded or strained to fit.

Layers of different lattice constants share one in-plane lattice only with an explicit strain_allocation; the strain of every layer is recorded. Every structure is an unrelaxed starting geometry, neutral, with the lowest spin multiplicity the electron count allows (not a ground-state prediction).

Module Attributes

PRESETS

material -> (sublattice A, sublattice B, lattice constant in angstrom, interlayer spacing).

Functions

build_honeycomb_stack(recipe)

A monolayer or stacked honeycomb cell, or a refusal with the reason.

build_twisted_bilayer(recipe)

A commensurate twisted bilayer, or a refusal with the reason (never a rounded angle).

commensurate_twists([max_atoms, min_angle, ...])

Every commensurate cell of at most max_atoms atoms, by angle (one cell per angle).

twist_cell(m, r)

Angle, bottom-layer superlattice matrix and atom count of the (m, r) cell.

Classes

HoneycombLayer(*[, material, a_site, b_site, a])

One honeycomb layer: a preset material or explicit sublattice chemistry.

HoneycombStackRecipe(*, identifier[, ...])

A honeycomb monolayer or AA, AB, ABC or AA' multilayer, 2-D or bulk.

TwistedBilayerRecipe(*, identifier[, ...])

A commensurate twisted bilayer from coprime (m, r), or an exactly matching angle.

class vibesketcher.chem.layered_carbon.HoneycombLayer(*, material='graphene', a_site=None, b_site=None, a=None)[source]

Bases: BaseModel

One honeycomb layer: a preset material or explicit sublattice chemistry.

Parameters:
  • material (Literal['graphene', 'hbn', 'custom'])

  • a_site (str | None)

  • b_site (str | None)

  • a (Annotated[float | None, Ge(ge=1.5), Le(le=10), AllowInfNan(allow_inf_nan=False)])

model_config = {'extra': 'forbid'}

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

material: Literal['graphene', 'hbn', 'custom']
a_site: str | None

Elements on sublattices A and B (custom layers only).

b_site: str | None
a: float | None

The in-plane lattice constant, angstrom (a preset’s default when left out).

sublattices()[source]
Return type:

tuple[str, str]

lattice_constant()[source]
Return type:

float

spacing()[source]
Return type:

float | None

class vibesketcher.chem.layered_carbon.HoneycombStackRecipe(*, identifier, interlayer=None, periodicity='2d', vacuum=15.0, strain_allocation='none', kind='honeycomb_stack', layers=<factory>, stacking='AA')[source]

Bases: _LayeredRecipe

A honeycomb monolayer or AA, AB, ABC or AA’ multilayer, 2-D or bulk.

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

  • interlayer (Annotated[float | None, Ge(ge=2.5), Le(le=10), AllowInfNan(allow_inf_nan=False)])

  • periodicity (Literal['2d', '3d'])

  • vacuum (Annotated[float, Ge(ge=3), Le(le=200), AllowInfNan(allow_inf_nan=False)])

  • strain_allocation (Literal['none', 'bottom', 'top', 'mean'])

  • kind (Literal['honeycomb_stack'])

  • layers (Annotated[list[HoneycombLayer], MinLen(min_length=1), MaxLen(max_length=24)])

  • stacking (Literal['AA', 'AB', 'ABC', "AA'"])

kind: Literal['honeycomb_stack']
layers: list[HoneycombLayer]
stacking: Literal['AA', 'AB', 'ABC', "AA'"]
model_config = {'extra': 'forbid'}

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

class vibesketcher.chem.layered_carbon.TwistedBilayerRecipe(*, identifier, interlayer=None, periodicity='2d', vacuum=15.0, strain_allocation='none', kind='twisted_bilayer', m=None, r=None, angle_deg=None, angle_tolerance_deg=1e-06, layers=<factory>, registry='AA', max_atoms=2000)[source]

Bases: _LayeredRecipe

A commensurate twisted bilayer from coprime (m, r), or an exactly matching angle.

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

  • interlayer (Annotated[float | None, Ge(ge=2.5), Le(le=10), AllowInfNan(allow_inf_nan=False)])

  • periodicity (Literal['2d', '3d'])

  • vacuum (Annotated[float, Ge(ge=3), Le(le=200), AllowInfNan(allow_inf_nan=False)])

  • strain_allocation (Literal['none', 'bottom', 'top', 'mean'])

  • kind (Literal['twisted_bilayer'])

  • m (Annotated[int | None, Ge(ge=1), Le(le=1000)])

  • r (Annotated[int | None, Ge(ge=1), Le(le=1000)])

  • angle_deg (Annotated[float | None, Gt(gt=0), Lt(lt=60), AllowInfNan(allow_inf_nan=False)])

  • angle_tolerance_deg (Annotated[float, Gt(gt=0), Le(le=0.001)])

  • layers (Annotated[list[HoneycombLayer], MinLen(min_length=2), MaxLen(max_length=2)])

  • registry (Literal['AA', 'AB'])

  • max_atoms (Annotated[int, Ge(ge=4), Le(le=25000)])

kind: Literal['twisted_bilayer']
m: int | None
r: int | None
angle_deg: float | None
angle_tolerance_deg: float

How close a requested angle must be to a commensurate one to be accepted.

layers: list[HoneycombLayer]
registry: Literal['AA', 'AB']

AA (site over site) or AB (top A over bottom B).

Type:

Registry before the twist

max_atoms: int

The largest cell built; larger commensurate cells are refused.

model_config = {'extra': 'forbid'}

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

vibesketcher.chem.layered_carbon.build_honeycomb_stack(recipe)[source]

A monolayer or stacked honeycomb cell, or a refusal with the reason.

Parameters:

recipe (HoneycombStackRecipe)

Return type:

PeriodicStructure

vibesketcher.chem.layered_carbon.build_twisted_bilayer(recipe)[source]

A commensurate twisted bilayer, or a refusal with the reason (never a rounded angle).

Parameters:

recipe (TwistedBilayerRecipe)

Return type:

PeriodicStructure

vibesketcher.chem.layered_carbon.commensurate_twists(max_atoms=2000, min_angle=0.0, max_angle=60.0)[source]

Every commensurate cell of at most max_atoms atoms, by angle (one cell per angle).

Parameters:
Return type:

list[dict[str, Any]]

vibesketcher.chem.layered_carbon.twist_cell(m, r)[source]

Angle, bottom-layer superlattice matrix and atom count of the (m, r) cell.

Parameters:
Return type:

dict[str, Any]