Executable Python examples

These small examples exercise the supported Python API during every documentation build. They are intentionally deterministic and avoid graphical windows, output files, and external executables.

Slab and enumeration setup

Create a toy slab, identify its Cartesian layers, and configure an enumeration transformation:

from pymatgen.core import Lattice

from surface_pd.core import EnumerationSlab, SurfaceEnumerator

slab = EnumerationSlab(
    Lattice.tetragonal(3.0, 15.0),
    ["Li", "Li"],
    [[0.0, 0.0, 0.2], [0.0, 0.0, 0.8]],
    enumerated_species=["Li"],
    num_enumerated_layers={"Li": 1},
    symmetric=True,
)
analysis = slab.analyze()
populations = [
    layer.species_counts["Li"] for layer in analysis.layers
]
print(populations)

enumerator = SurfaceEnumerator(
    {"Li": {"Li": 0.5}},
    min_cell_size=1,
    max_cell_size=1,
)
print((enumerator.min_cell_size, enumerator.max_cell_size))

[1, 1]
(1, 1)

The example configures enumeration but does not call apply_enumeration(), because that operation requires the external enumlib executables. See Surface-enumeration command reference for the command reference and the examples-owned command-line walkthrough for the runnable workflow.

Grand-potential calculation

Construct a one-phase dataset and evaluate its surface energy at one voltage and temperature:

from surface_pd.thermodynamics import (
    ConstantChemicalPotential,
    GrandPotentialModel,
    Phase,
    PhaseDataset,
    ThermodynamicState,
)
phase = Phase(
    "example",
    {"A": 2, "B": 1},
    dft_energy_ev=-8.0,
    surface_area_angstrom2=9.0,
    number_of_surfaces=2,
)
dataset = PhaseDataset(
    "surface",
    ("A", "B"),
    (phase,),
    "demonstration values (not for scientific use)",
)
model = GrandPotentialModel(
    ("A", "B"),
    {
        "A": ConstantChemicalPotential(-2.0),
        "B": ConstantChemicalPotential(-3.0),
    },
    (),
)
result = model.evaluate(dataset, ThermodynamicState({}))
print(result.surface_grand_potential_ev_per_angstrom2.shape)
print(result.surface_grand_potential_ev_per_angstrom2[0])

(1,)
-0.05555555555555555

The numerical values above are deliberately synthetic. Real calculations must use reference phases and chemical-potential parameters obtained with settings consistent with the slab energies, as described in Versioned JSON configuration.