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_allocationis 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
|
What a constructed model is not; carried in every record. |
Functions
|
A heterointerface of two parent slabs, or a refusal with the reason. |
|
A stacking-fault model with one fault per cell (periodic) or between surfaces (slab). |
|
Commensurate in-plane supercells of two 2-D lattices (rows), best first. |
|
The ranked coincidence cells of two parent slabs, with atom counts; nothing is built. |
|
A planned-only grain-boundary or dislocation record, or coded refusals. |
|
Build without storing: the record and structure, or a refusal with the reason. |
Classes
|
A dislocation to plan: Burgers vector, line direction and boundary/elastic model. |
|
A grain boundary to plan: every geometric and boundary assumption is explicit. |
|
Two parent slabs on one commensurate in-plane cell, bottom first. |
|
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:
_RecipeTwo 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}$')])
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)])
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)])
- kind: Literal['interface']¶
- 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.
- twist_deg: float | None¶
Rotation of the top phase about the normal, degrees; None searches every rotation.
- 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)
- periodicity: Literal['2d', '3d']¶
- periodic_gap: float | None¶
the second interface’s gap (top phase to the bottom image).
- Type:
3-D models only
- 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:
_RecipeAn 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)])
fault (Literal['intrinsic', 'extrinsic', 'shift'])
model (Literal['periodic', 'slab'])
vacuum (Annotated[float, Ge(ge=3), Le(le=200), AllowInfNan(allow_inf_nan=False)])
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']¶
- miller: tuple[int, int, int]¶
The fault plane, in the bulk cell’s rows (conventional cell for a template).
- fault: Literal['intrinsic', 'extrinsic', 'shift']¶
- displacement: tuple[float, float] | None¶
the rigid in-plane displacement, fractions of the surface cell.
- Type:
shiftonly
- fault_plane: int | None¶
Planes with this index and above (0 = bottom) are displaced; the middle by default.
- model: Literal['periodic', 'slab']¶
- min_image_separation: float¶
The closest a fault may come to its periodic image (or twice to a free surface).
- 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:
recipe (InterfaceRecipe)
document (Document)
- Return type:
- 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:
recipe (StackingFaultRecipe)
document (Document | None)
- Return type:
- 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_areasquare angstrom whose principal mismatch is at mostmax_strain. Withtwist_degset, only coincidences whose top-phase rotation lies withinangle_tolerance_degof it (modulo the lattices’ point rotations) are kept;Noneadmits 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.
- 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.
- 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.
- vibesketcher.document.interfaces.preview(recipe, document)[source]¶
Build without storing: the record and structure, or a refusal with the reason.
- Parameters:
recipe (InterfaceRecipe | StackingFaultRecipe)
document (Document | None)
- Return type: