core

SurfaceEnumerator class

class surface_pd.core.SurfaceEnumerator(replacements: dict, min_cell_size: int = 1, max_cell_size: int = 1, enum_precision_parameter: float = 1e-05)

Enumerate ordered surface structures at a defined composition.

Parameters:

• replacements (dict) – Enumerated parent species mapped to replacement-species fractional occupancies. A sum below one represents vacancies, for example {"Li": {"Li": 0.5}}. Multiple replacement species represent substitutional orderings.

• min_cell_size (int, default=1) – Minimum in-plane surface-cell area multiplier.

• max_cell_size (int, default=1) – Maximum in-plane surface-cell area multiplier.

• enum_precision_parameter (float, default=1e-5) – Positive finite-coordinate tolerance passed to enumlib.

Notes

Enumeration requires a working enumlib installation discoverable by pymatgen. Temporary marker species are managed internally. Enumlib ranks symmetrically distinct raw candidates. Accepted candidates retain that order, and surface-pd does not apply a second structure-matching or deduplication pass after surface filtering or symmetric finalization. Callers that require a different, tolerance-dependent equivalence policy can explicitly compare selected results with pymatgen’s StructureMatcher.

apply_enumeration(structure: EnumerationSlab, max_structures: int = 2000)

Enumerate ordered in-plane derivatives of a parent slab.

Parameters:

• structure (EnumerationSlab) – Configured parent slab. The slab is not mutated.

• max_structures (int, default=2000) – Positive limit on ranked raw candidates requested from pymatgen. Surface filtering and finalization happen afterward, so fewer structures may be returned. Enumeration is not repeated to fill this limit with finalized structures.

Returns:

Finalized surface slabs whose supercells expand only in plane. Each result exposes immutable enumeration_metadata containing its transformation, area multiplier, raw rank, and symmetry mode.

Return type:

list of EnumerationSlab

Raises:

RuntimeError – If pymatgen cannot execute enumlib.

SurfaceEnumerationMetadata class

class surface_pd.core.SurfaceEnumerationMetadata(transformation_matrix: tuple[tuple[int, int, int], ...], area_multiplier: int, raw_candidate_rank: int, symmetric: bool)

Provenance for one finalized surface-enumeration result.

Parameters:

• transformation_matrix (tuple of tuple of int) – Integer transformation from the parent lattice to the result lattice.

• area_multiplier (int) – In-plane surface-cell area multiplier.

• raw_candidate_rank (int) – Zero-based position in the ranked raw pymatgen result list.

• symmetric (bool) – Whether symmetric two-surface finalization was applied.

EnumerationSlab class

The supported slab API consists of the two high-level factories, immutable analysis, inversion-symmetry inspection, surface-enumeration configuration properties, and finalized-result metadata. Geometry repair and legacy command pipeline operations are internal implementation details.

class surface_pd.core.EnumerationSlab(lattice: list | ndarray | Lattice, species: Sequence[str | Element | Species | DummySpecies | Composition], coords: Sequence[Sequence[float]], charge: float = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: dict = None, labels: Sequence[str | None] | None = None, properties: dict | None = None, *, direction: int = 2, layer_tolerance_angstrom: float = 0.5, enumerated_species: Sequence[str] | None = None, num_enumerated_layers: Mapping[str, int] | None = None, symmetric: bool | None = None)

Represent and manipulate a periodic surface slab.

Parameters:

• lattice (Lattice or array-like of shape (3, 3)) – Periodic lattice accepted by pymatgen.core.Structure.

• species (sequence) – Species for the sites, in the same order as coords.

• coords (sequence of sequence of float) – Fractional coordinates unless coords_are_cartesian is true.

• charge (float, optional) – Overall structure charge.

• validate_proximity (bool, default=False) – Reject sites separated by less than pymatgen’s proximity threshold.

• to_unit_cell (bool, default=False) – Wrap fractional coordinates into the unit cell during construction.

• coords_are_cartesian (bool, default=False) – Interpret coords as Cartesian coordinates when true.

• site_properties (dict, optional) – Per-site property sequences accepted by pymatgen.

• labels (sequence of str or None, optional) – Optional label for each site, accepted by pymatgen.

• properties (dict, optional) – Structure-level properties accepted by pymatgen.

• direction (int, default=2) – Lattice-axis index containing the broken periodicity and vacuum region. The corresponding vector need not be perpendicular to the surface plane. Must be 0, 1, or 2.

• layer_tolerance_angstrom (float, default=0.5) – Positive finite maximum Cartesian span of sites grouped into one layer, in angstroms.

• enumerated_species (sequence of str, optional) – Unique, nonempty species names whose surface sites will be enumerated.

• num_enumerated_layers (mapping of str to int, optional) – Positive number of outer layers to enumerate for each target species.

• symmetric (bool, optional) – Whether enumeration operates on both slab surfaces. None denotes an unconfigured slab.

Notes

Surface-pd configuration parameters are keyword-only. They initialize validated public properties while their values are stored privately.

analyze()

Return an immutable analysis snapshot of the current slab state.

property direction

Lattice-axis index containing the slab’s vacuum region.

The corresponding lattice vector need not be perpendicular to the surface plane. Valid axis indices are 0, 1, and 2.

Type:

int

property enumerated_species

Species selected for enumeration.

Values must be unique, nonempty strings. Assigned sequences are copied.

Type:

List of str or None

property enumeration_metadata

Finalization provenance.

Type:

SurfaceEnumerationMetadata or None

classmethod from_file(filename: str | PathLike, primitive: bool = False, sort: bool = False, merge_tol: float = 0.0, *, direction: int, layer_tolerance_angstrom: float = 0.5, enumerated_species: Sequence[str] | None = None, num_enumerated_layers: Mapping[str, int] | None = None, symmetric: bool | None = None, **kwargs)

Read a structure file and configure it for surface enumeration.

File-format detection and parsing are delegated to pymatgen.core.Structure.from_file(). The parsed structure is then converted through from_structure(), so file-based and in-memory construction use the same surface configuration and validation.

Parameters:

• filename (str or path-like) – Structure file in a format supported by pymatgen.

• primitive (bool, default=False) – Ask pymatgen to return a primitive structure where supported.

• sort (bool, default=False) – Ask pymatgen to sort sites by its standard ordering.

• merge_tol (float, default=0.0) – Cartesian distance in angstroms within which pymatgen merges sites while parsing.

• direction (int) – Lattice-axis index containing the slab’s broken periodicity and vacuum region.

• layer_tolerance_angstrom (float, default=0.5) – Maximum Cartesian span of one layer, in angstroms.

• enumerated_species (sequence of str, optional) – Species whose outer surface layers may be modified.

• num_enumerated_layers (mapping of str to int, optional) – Independent outer-layer count for each enumerated species.

• symmetric (bool, optional) – Whether corresponding layers on both surfaces are selected.

• **kwargs – Additional keyword arguments passed to pymatgen’s file parser.

Returns:

Parsed independent structure configured for surface enumeration.

Return type:

EnumerationSlab

classmethod from_structure(structure: Structure, *, direction: int, layer_tolerance_angstrom: float = 0.5, enumerated_species: Sequence[str] | None = None, num_enumerated_layers: Mapping[str, int] | None = None, symmetric: bool | None = None)

Construct an enumeration slab from a pymatgen structure.

Parameters:

• structure (Structure) – Source structure whose lattice, sites, charge, labels, site properties, and structure properties are copied.

• direction (int) – Lattice-axis index containing the slab’s broken periodicity and vacuum region.

• layer_tolerance_angstrom (float, default=0.5) – Maximum Cartesian span of one layer, in angstroms.

• enumerated_species (sequence of str, optional) – Species whose outer surface layers may be modified.

• num_enumerated_layers (mapping of str to int, optional) – Independent outer-layer count for each enumerated species.

• symmetric (bool, optional) – Whether corresponding layers on both surfaces are selected.

Returns:

Independent copy configured for surface enumeration.

Return type:

EnumerationSlab

has_inversion_symmetry(symprec: float = 0.1)

Return whether the slab has inversion symmetry.

Parameters:

symprec (float, default=0.1) – Cartesian symmetry tolerance in angstroms.

property layer_tolerance_angstrom

Maximum Cartesian span of one layer, in angstroms.

The value must be positive and finite.

Type:

float

property num_enumerated_layers

Number of enumerated layers for each target species.

Keys must be nonempty strings and values positive integers. Assigned mappings are copied.

Type:

Dict or None

property symmetric

Whether both slab surfaces are enumerated.

The value must be a boolean or None.

Type:

Bool or None

SlabLayer class

class surface_pd.core.SlabLayer(coordinate: float, site_indices: tuple[int, ...], species_counts: Mapping[str, int])

Immutable description of one Cartesian slab layer.

coordinate

Mean coordinate in angstroms along the oriented normal to the plane spanned by the two periodic lattice vectors.

Type:

float

site_indices

Indices of sites assigned to this layer.

Type:

tuple of int

species_counts

Number of sites of each element in the layer.

Type:

mapping of str to int

SlabAnalysis class

class surface_pd.core.SlabAnalysis(layers: tuple[SlabLayer, ...], enumerated_site_indices: Mapping[str, tuple[int, ...]], fixed_site_indices: tuple[int, ...], fixed_region_bounds_angstrom: tuple[float, float] | None)

Immutable analysis of one state of an enumeration slab.

layers

Cartesian layers ordered from the bottom to the top surface.

Type:

tuple of SlabLayer

enumerated_site_indices

Selected site indices grouped by enumerated parent species.

Type:

mapping of str to tuple of int

fixed_site_indices

Sites whose selective-dynamics flags are all false.

Type:

tuple of int

fixed_region_bounds_angstrom

Minimum and maximum fixed-site coordinates in the layer coordinate system. None indicates that the slab has no fixed sites.

Type:

tuple of float or None