Structure Transformers Engine Utility

Build and transform structures with ASE-based geometry utilities.

This module provides reusable structure-construction and transformation helpers for slab generation, supercell/lattice transforms, and random molecular placement inside periodic cells. It is focused on geometry preparation and does not perform engine-specific simulation logic.

Usage context

• Pre-processing: Build slabs/supercells before simulation input generation.
• Cell transformations: Re-map lattices into alternate simulation-friendly forms.
• Packing workflows: Place molecules stochastically under distance constraints.

Function: build_surface

Build a surface slab from a bulk structure using Miller indices.

Parameters:

Name	Type	Description	Default
bulk	Atoms	Input bulk structure.	required
miller	Tuple[int, int, int]	Miller index triple defining the surface orientation.	required
layers	int	Number of atomic layers to include in the slab.	required
vacuum	float	Vacuum padding along the surface normal.	15.0
center	bool	Whether to center slab atoms along z after slab construction.	True

Returns:

Type	Description
Atoms	Generated slab structure.

Examples:

slab = build_surface(bulk, (1, 1, 1), layers=6, vacuum=15.0)

Function: make_supercell

Generate a supercell or apply a lattice transformation matrix.

Parameters:

Name	Type	Description	Default
atoms	Atoms	Input structure to transform.	required
transform	Iterable[Iterable[int]] | Tuple[int, int, int]	Either repetition counts (nx, ny, nz) or a 3x3 integer matrix.	required

Returns:

Type	Description
Atoms	Transformed supercell structure.

Examples:

sc = make_supercell(atoms, (2, 2, 1))

Function: orthogonalize_hexagonal_cell

Convert a hexagonal unit cell into an orthorhombic supercell mapping.

Parameters:

Name	Type	Description	Default
atoms	Atoms	Input structure with a hexagonal-like cell representation.	required

Returns:

Type	Description
Atoms	Structure transformed with a fixed integer supercell matrix.

Examples:

ortho = orthogonalize_hexagonal_cell(hex_atoms)

Function: place2

Randomly place molecule copies into a periodic simulation cell.

Generates random rigid-body rotations/translations for n_copies of an inserted molecule and accepts placements that satisfy a minimum interatomic-distance constraint under periodic boundary conditions.

Parameters:

Name	Type	Description	Default
insert_molecule	str | Path	Structure file for the molecule to insert repeatedly.	required
base_structure	Optional[str | Path]	Optional initial structure preloaded into the target cell.	None
n_copies	int	Number of inserted molecule copies to place.	required
box_length_x	float	Cell length along x.	required
box_length_y	float	Cell length along y.	required
box_length_z	float	Cell length along z.	required
alpha	float	Cell angle alpha in degrees.	required
beta	float	Cell angle beta in degrees.	required
gamma	float	Cell angle gamma in degrees.	required
min_interatomic_distance	float	Minimum allowed distance between inserted and existing atoms.	required
base_structure_placement_mode	str	Placement mode for base structure: "as-is", "center", or "origin".	'as-is'
max_placement_attempts_per_copy	int	Maximum random attempts before failing one copy placement.	50000
random_seed	int | None	Seed for deterministic random placement.	None

Returns:

Type	Description
Atoms	Combined packed structure with periodic boundary conditions enabled.

Examples:

packed = place2(
    "h2o.xyz",
    n_copies=50,
    box_length_x=30.0,
    box_length_y=30.0,
    box_length_z=30.0,
    alpha=90.0,
    beta=90.0,
    gamma=90.0,
    min_interatomic_distance=1.4,
)