vibe-sketcherDocumentation

vibesketcher.document.interfaces

Periodic interfaces, stacking faults and planned extended defects (#197).

Every model built here is an unrelaxed starting geometry. Construction is not relaxation, thermodynamic stability, adhesion or validated mechanics; each record says so and lists the strain and size convergence a calculation on it still owes.

Heterointerfaces (kind: "interface")

Two parent slabs in the document (any slab-like cell: in-plane rows a, b with no normal component and c along the normal) are put on one in-plane lattice. The coincidence search follows A. Zur and T. C. McGill, J. Appl. Phys. 55, 378 (1984), doi:10.1063/1.333084: every superlattice of index n of a 2-D lattice is an integer Hermite normal form matrix [[a, b], [0, d]] with a d = n and 0 <= b < d times the parent rows. Superlattices of the two phases with equal area within the strain bound are reduced (Lagrange-Gauss), compared, and the integer basis correspondence with the smallest principal strain is kept. The map F that takes the top superlattice onto the bottom one is split by polar decomposition into the in-plane rotation of the top phase and its stretch; the principal values of the stretch minus one are the lattice mismatch. Candidates are ranked by mismatch, then area. Both integer supercell matrices are recorded.

The common cell is C = S_bottom + w (R S_top - S_bottom): w = 0 keeps the bottom lattice and strains the top, w = 1 the reverse, w = 0.5 shares the mismatch. strain_allocation is required for any nonzero mismatch; no phase is ever strained silently. Each phase’s strain is recorded as the left stretch tensor minus the identity (Biot strain, interface frame); the normal axis is not strained, so no Poisson response is applied.

Stacking faults (kind: "stacking_fault")

A bulk crystal is oriented on its close-packed plane (the slab surface transform of W. Sun and G. Ceder, Surf. Sci. 617, 53, 2013) and stacked. Planes above the fault plane are displaced rigidly in-plane, as in the generalised stacking-fault construction of V. Vitek, Philos. Mag. 18, 773 (1968). For an ABC close-packed stack the stacking offset delta (the Shockley partial, a/6 <112> in fcc) is measured from the planes themselves: an intrinsic fault shifts every plane above the fault by delta (one plane missing, ABC|BCA), an extrinsic fault shifts the planes above the fault by delta and those above the next plane by a further delta (one plane inserted); J. P. Hirth and J. Lothe, Theory of Dislocations, 2nd ed. (Wiley, 1982), ch. 9-10. A periodic model tilts c by the total displacement, so each cell holds exactly one fault; a slab model carries vacuum. The fault is refused when it is closer to its periodic image, or to a free surface, than the stated minimum.

Grain boundaries and dislocations

Only planned here: plan_extended_defect() returns a planned record when the rotation axis, misorientation and boundary plane (grain boundaries) or Burgers vector, line direction and boundary/elastic assumptions (dislocations) are all stated, and coded refusals listing what is missing otherwise. No atoms are placed.

Module Attributes

NOT_CLAIMED

What a constructed model is not; carried in every record.

Functions

build_interface(recipe, document)

A heterointerface of two parent slabs, or a refusal with the reason.

build_stacking_fault(recipe[, document])

A stacking-fault model with one fault per cell (periodic) or between surfaces (slab).

coincidence_cells(bottom, top, *, max_area, ...)

Commensurate in-plane supercells of two 2-D lattices (rows), best first.

interface_matches(document, bottom, top, *)

The ranked coincidence cells of two parent slabs, with atom counts; nothing is built.

plan_extended_defect(data[, document])

A planned-only grain-boundary or dislocation record, or coded refusals.

preview(recipe, document)

Build without storing: the record and structure, or a refusal with the reason.

Classes

DislocationPlan(*[, source, template, ...])

A dislocation to plan: Burgers vector, line direction and boundary/elastic model.

GrainBoundaryPlan(*[, source, template, ...])

A grain boundary to plan: every geometric and boundary assumption is explicit.

InterfaceRecipe(*[, kind, bottom_matrix, ...])

Two parent slabs on one commensurate in-plane cell, bottom first.

StackingFaultRecipe(*[, kind, source, ...])

An intrinsic, extrinsic or explicitly shifted fault in a stack of planes.

class vibesketcher.document.interfaces.InterfaceRecipe(*, kind='interface', identifier, bottom, top, bottom_matrix=None, top_matrix=None, match=0, max_area=150.0, max_strain=0.05, twist_deg=0.0, angle_tolerance_deg=0.5, strain_allocation='none', top_weight=None, translation=(0.0, 0.0), gap, top_flip=False, periodicity='2d', vacuum=15.0, periodic_gap=None, min_distance=1.0, max_atoms=2000)[source]

Bases: _Recipe

Two parent slabs on one commensurate in-plane cell, bottom first.

Parameters:
  • kind (Literal['interface'])

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

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

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

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

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

  • match (Annotated[int, Ge(ge=0), Le(le=99)])

  • max_area (Annotated[float, Gt(gt=0), Le(le=5000), AllowInfNan(allow_inf_nan=False)])

  • max_strain (Annotated[float, Ge(ge=0), Le(le=0.15), AllowInfNan(allow_inf_nan=False)])

  • twist_deg (Annotated[float | None, Ge(ge=-180), Le(le=180), AllowInfNan(allow_inf_nan=False)])

  • angle_tolerance_deg (Annotated[float, Gt(gt=0), Le(le=30), AllowInfNan(allow_inf_nan=False)])

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

  • top_weight (Annotated[float | None, Ge(ge=0), Le(le=1), AllowInfNan(allow_inf_nan=False)])

  • translation (tuple[float, float])

  • gap (Annotated[float, Ge(ge=0.5), Le(le=20), AllowInfNan(allow_inf_nan=False)])

  • top_flip (bool)

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

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

  • periodic_gap (Annotated[float | None, Ge(ge=0.5), Le(le=20), AllowInfNan(allow_inf_nan=False)])

  • min_distance (Annotated[float, Gt(gt=0.3), Le(le=5), AllowInfNan(allow_inf_nan=False)])

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

kind: Literal['interface']
identifier: str
bottom: str

The substrate (lower) slab and the overlayer (upper) slab in the document.

top: str
bottom_matrix: list[list[int]] | None

Explicit integer supercell matrices (rows of the parents’ a and b); without them the ranked coincidence search picks candidate match.

top_matrix: list[list[int]] | None
match: int
max_area: float
max_strain: float
twist_deg: float | None

Rotation of the top phase about the normal, degrees; None searches every rotation.

angle_tolerance_deg: float
strain_allocation: StrainAllocation

none (refuse any mismatch), bottom (strain the top), top (strain the bottom), mean, or weighted with top_weight.

Type:

Whose lattice is kept

top_weight: float | None

0 keeps it unstrained.

Type:

Fraction of the mismatch the bottom phase takes (weighted only)

translation: tuple[float, float]

In-plane shift of the top phase, fractions of the interface cell.

gap: float

Normal distance from the highest bottom atom to the lowest top atom, angstrom.

top_flip: bool

Turn the top slab over so its recorded top termination faces the interface.

periodicity: Literal['2d', '3d']
vacuum: float

Vacuum along the normal for a 2-D model, angstrom.

periodic_gap: float | None

the second interface’s gap (top phase to the bottom image).

Type:

3-D models only

min_distance: float

Closest interphase contact admitted, angstrom.

max_atoms: int
model_config = {'extra': 'forbid'}

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

class vibesketcher.document.interfaces.StackingFaultRecipe(*, kind='stacking_fault', identifier, source=None, template=None, template_a=None, miller=(1, 1, 1), planes=12, fault, displacement=None, fault_plane=None, model='periodic', vacuum=15.0, repeat=(1, 1), min_image_separation=10.0, plane_tolerance=0.05, min_distance=1.0, surface_cell='primitive')[source]

Bases: _Recipe

An intrinsic, extrinsic or explicitly shifted fault in a stack of planes.

Parameters:
  • kind (Literal['stacking_fault'])

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

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

  • template (str | None)

  • template_a (Annotated[float | None, Gt(gt=0), AllowInfNan(allow_inf_nan=False)])

  • miller (tuple[int, int, int])

  • planes (Annotated[int, Ge(ge=3), Le(le=240)])

  • fault (Literal['intrinsic', 'extrinsic', 'shift'])

  • displacement (tuple[float, float] | None)

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

  • model (Literal['periodic', 'slab'])

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

  • repeat (tuple[int, int])

  • min_image_separation (Annotated[float, Gt(gt=0), Le(le=200), AllowInfNan(allow_inf_nan=False)])

  • plane_tolerance (Annotated[float, Gt(gt=0), Le(le=0.5), AllowInfNan(allow_inf_nan=False)])

  • min_distance (Annotated[float, Gt(gt=0.3), Le(le=5), AllowInfNan(allow_inf_nan=False)])

  • surface_cell (Literal['primitive', 'given'])

kind: Literal['stacking_fault']
identifier: str
source: str | None

The bulk structure in the document; or give template (e.g. cu).

template: str | None
template_a: float | None
miller: tuple[int, int, int]

The fault plane, in the bulk cell’s rows (conventional cell for a template).

planes: int

Atomic planes along the normal; a whole number of oriented bulk repeats.

fault: Literal['intrinsic', 'extrinsic', 'shift']
displacement: tuple[float, float] | None

the rigid in-plane displacement, fractions of the surface cell.

Type:

shift only

fault_plane: int | None

Planes with this index and above (0 = bottom) are displaced; the middle by default.

model: Literal['periodic', 'slab']
vacuum: float
repeat: tuple[int, int]
min_image_separation: float

The closest a fault may come to its periodic image (or twice to a free surface).

plane_tolerance: float
min_distance: float
surface_cell: Literal['primitive', 'given']
model_config = {'extra': 'forbid'}

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

vibesketcher.document.interfaces.build_interface(recipe, document)[source]

A heterointerface of two parent slabs, or a refusal with the reason.

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.interfaces.build_stacking_fault(recipe, document=None)[source]

A stacking-fault model with one fault per cell (periodic) or between surfaces (slab).

Parameters:
Return type:

PeriodicStructure

vibesketcher.document.interfaces.coincidence_cells(bottom, top, *, max_area, max_strain, twist_deg=0.0, angle_tolerance_deg=0.5, max_candidates=20)[source]

Commensurate in-plane supercells of two 2-D lattices (rows), best first.

Zur and McGill (1984): superlattices of both phases of at most max_area square angstrom whose principal mismatch is at most max_strain. With twist_deg set, only coincidences whose top-phase rotation lies within angle_tolerance_deg of it (modulo the lattices’ point rotations) are kept; None admits every rotation and records it. Coincidences equal up to those point rotations, and larger cells with the rotation and mismatch of a smaller one, are listed once.

Parameters:
  • bottom (NDArray[float64])

  • top (NDArray[float64])

  • max_area (float)

  • max_strain (float)

  • twist_deg (float | None)

  • angle_tolerance_deg (float)

  • max_candidates (int)

Return type:

list[dict[str, Any]]

vibesketcher.document.interfaces.interface_matches(document, bottom, top, *, max_area=150.0, max_strain=0.05, twist_deg=0.0, angle_tolerance_deg=0.5, top_flip=False, max_candidates=20)[source]

The ranked coincidence cells of two parent slabs, with atom counts; nothing is built.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.interfaces.plan_extended_defect(data, document=None)[source]

A planned-only grain-boundary or dislocation record, or coded refusals.

No atoms are placed. The plan is admitted only when its assumptions are complete; a missing item is a refusal with a stable code, never a default.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.interfaces.preview(recipe, document)[source]

Build without storing: the record and structure, or a refusal with the reason.

Parameters:
Return type:

dict[str, Any]