core

EnumWithComposition class

class surface_pd.core.EnumWithComposition(subs_dict: 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:

• subs_dict (dict) – Mapping accepted by pymatgen’s SubstitutionTransformation. Each key identifies a species in the parent slab and each value maps replacement species to fractional occupancies, for example {"X": {"Li": 0.5, "O": 0.5}}.

• min_cell_size (int, default=1) – Minimum multiple of the parent cell passed to enumlib. Must be positive and no larger than max_cell_size.

• max_cell_size (int, default=1) – Maximum multiple of the parent cell passed to enumlib. Must be positive and no smaller than min_cell_size.

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

Notes

Enumeration requires a working enumlib installation discoverable by pymatgen. Validation of substitutions and cell-size bounds is delegated to pymatgen.

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

Enumerate ordered derivatives of a parent slab.

Parameters:

• structure (EnumerationSlab) – Parent slab to substitute and enumerate. The slab is not mutated.

• max_structures (int, default=2000) – Maximum number of ranked structures requested from pymatgen. Must be positive.

Returns:

Pymatgen ranked-result dictionaries. Each dictionary contains a structure entry and ranking metadata supplied by EnumerateStructureTransformation.

Return type:

list of dict

Raises:

RuntimeError – If pymatgen cannot execute enumlib.

Notes

Validation errors raised by pymatgen are propagated unchanged.

EnumerationSlab class

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, tolerance: float = 0.03, to_be_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 normal to the surface. Must be 0, 1, or 2.

• tolerance (float, default=0.03) – Positive finite fractional-coordinate tolerance used to group layers.

• to_be_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.

add_selective_dynamics(lower_limit: float, upper_limit: float)

Add selective dynamics to a refined slab model.

Parameters:

• lower_limit (float) – Lower fractional-coordinate bound of the fixed central region.

• upper_limit (float) – Upper fractional-coordinate bound of the fixed central region.

Returns:

Deep copy with fixed flags inside the central region and relaxed flags outside it. The receiver is not mutated.

Return type:

EnumerationSlab

calculate_num_sites(composition_list: list, relaxed_index: dict, max_cell_size: int)

Calculate the number of sites for the user-defined composition.

Parameters:

• composition_list (list[float]) – Target occupancy fraction for each enumerated species.

• relaxed_index (dict[str, list[int]]) – Enumerated species mapped to their relaxed surface-site indices.

• max_cell_size (int) – Cell-size multiple used for enumeration.

Returns:

Expected number of sites after applying the composition.

Return type:

int

Raises:

NonIntegerError – If the calculated site count is not effectively integral.

check_rotate(criteria: float)

Check if the slab needs rotation to satisfy the cuboid requirement.

Parameters:

criteria (float) – Target lattice length in angstroms for the surface-normal axis.

Returns:

A deep copy, rotated when another lattice axis matches criteria. None is returned when rotation is needed but no axis matches.

Return type:

EnumerationSlab or None

property direction

Lattice-axis index perpendicular to the surface.

Valid axis indices are 0, 1, and 2.

Type:

int

generate_supplemental_structures(subs_dict: dict, relaxed_index: dict)

Generate supplemental structures.

Supplemental structures include the cases that the to-be-enumerated structure is straight forward to generate and does not require the EnumWithComposition class to involve.

Parameters:

• subs_dict (dict) – Target species mapped to replacement-species occupancies.

• relaxed_index (dict[str, list[int]]) – Target species mapped to surface-site indices.

Returns:

Deep copy with sites removed where the target species has zero occupancy. The receiver is not mutated.

Return type:

EnumerationSlab

get_center_sites()

Get center sites from fixed selective dynamics flags.

Returns:

Lower and upper fractional-coordinate bounds of the fixed region, followed by a new slab containing its fixed sites.

Return type:

tuple[float, float, EnumerationSlab]

get_max_min_c_frac()

Get the maximum and minimum fractional c coordinates.

Returns:

Minimum and maximum fractional coordinates along direction, in that order.

Return type:

tuple[float, float]

group_atoms_by_layer(layers: dict)

Group misclassified atoms into the right layers.

For example, c_atom1 = 0.01, c_atoms2 = 0.02, they should be classified in one layer. But actually they are not. So this function here will search the difference between two closest atoms, if the difference is smaller than diff, they will be regrouped in the same layer.

Parameters:

layers (dict[float, int]) – Fractional heights mapped to atom populations.

Returns:

Layer populations after adjacent heights within tolerance are merged. The input mapping is not mutated.

Return type:

dict[float, int]

index_extraction(only_top: bool = False)

Get target species indices in the relaxed surface layers.

Parameters:

only_top (bool, default=False) – Return only top-surface indices when true.

Returns:

Fixed-region bounds followed by site indices for each target species.

Return type:

tuple[float, float, dict[str, list[int]]]

is_symmetry(symprec: float = 0.1, return_isc: bool = False)

Check whether the slab model is symmetric.

If it is, the inversion symmetry center and the inversion operation are able to return.

Parameters:

• symprec (float, default=1e-1) – Cartesian symmetry tolerance in angstroms.

• return_isc (bool, default=False) – Return inversion-center details when true.

Returns:

With return_isc=False, whether the slab has Laue symmetry. With return_isc=True, a true flag, fractional inversion-center coordinates, and the pymatgen inversion operation are returned when found. None is returned if Laue symmetry is reported but no explicit inversion operation is available.

Return type:

bool or tuple[bool, numpy.ndarray, SymmOp] or None

layer_distinguisher()

Distinguish the layers that will be relaxed.

Returns:

Lower and upper bounds of the fixed region, followed by target layer heights for each enumerated species. Symmetric slabs contain top and bottom heights; asymmetric slabs contain only the top.

Return type:

tuple[float, float, dict[str, list[float]]]

layers_finder(precision: int = 2)

Find species layer populations by fractional coordinate.

Parameters:

precision (int, default=2) – Decimal places used to round fractional layer coordinates.

Returns:

Species mapped to fractional heights and atom populations.

Return type:

dict[str, dict[float, int]]

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

surface_substitute(dummy_species: list)

Substitute top-surface target species with dummy species.

Parameters:

dummy_species (list) – One pymatgen-compatible dummy species per enumerated species.

Returns:

Deep copy with top-surface target sites replaced. The receiver is not mutated.

Return type:

EnumerationSlab

property symmetric

Whether both slab surfaces are enumerated.

The value must be a boolean or None.

Type:

Bool or None

symmetrize_top_base(symprec: float = 0.0001)

Symmetrize the top surface by the inversion symmetry center.

This creates a fully enumerated slab model. The inversion symmetry center is determined based on the central fixed region only because the input slab model is not symmetric since on the one hand, the top surface of the slab is substituted by other dummy species, on the other hand, it has been enumerated with different Li and O compositions on the surface. Therefore, using the whole slab to detect the inversion symmetry does not work.

Parameters:

symprec (float, default=1e-4) – Cartesian symmetry tolerance in angstroms.

Returns:

New slab with equivalent top and bottom surfaces.

Return type:

EnumerationSlab

Raises:

NoInversionSymmetryError – If the fixed central region has no inversion symmetry.

Notes

The receiver is wrapped in place before the new slab is constructed. On symmetry failure, the central region is written to debug-center.vasp in the current working directory.

property to_be_enumerated_species

Species selected for enumeration.

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

Type:

List of str or None

property tolerance

Fractional-coordinate tolerance used to group layers.

The value must be positive and finite.

Type:

float

tune_c(target_min_c: float)

Slightly adjust the slab along the slab direction defined before.

This is to make sure that the central region is still located at around the same place.

Parameters:

target_min_c (float) – Desired minimum fractional coordinate along direction.

Returns:

This slab after translating its sites. Displacements smaller than tolerance are suppressed.

Return type:

EnumerationSlab

Notes

This method mutates the receiver and returns it for fluent use.

tune_isc(origin, shift_isc_back: bool = True)

Shift or shift back the inversion symmetry center.

Parameters:

• origin (array-like of shape (3,)) – Fractional translation applied when shift_isc_back is true. Otherwise this argument is ignored and the center is detected.

• shift_isc_back (bool, default=True) – Add origin when true; detect and subtract the current inversion center when false.

Returns:

This slab after shifting and wrapping its coordinates.

Return type:

EnumerationSlab

Notes

This method mutates the receiver and returns it for fluent use.

wrap_pbc()

Wrap fractional coordinates back into the unit cell.

Returns:

This slab after its site coordinates have been wrapped.

Return type:

EnumerationSlab

Notes

This method mutates the receiver and returns it for fluent use.