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 surface-normal layers, and configure an enumeration transformation:

from pymatgen.core import Lattice

from surface_pd.core import EnumerationSlab, EnumWithComposition

slab = EnumerationSlab(
    Lattice.tetragonal(3.0, 15.0),
    ["Li", "Li"],
    [[0.0, 0.0, 0.2], [0.0, 0.0, 0.8]],
    to_be_enumerated_species=["Li"],
    num_enumerated_layers={"Li": 1},
    symmetric=True,
)
populations = slab.layers_finder()["Li"]
print(sorted(populations.values()))

enumerator = EnumWithComposition(
    {"X": {"Li": 0.5, "O": 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 Slab model surface enumeration for the complete command-line workflow.

Surface-energy calculation

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

import numpy as np
import pandas as pd

from surface_pd.plot import PdData, ReferenceEnergies

references = ReferenceEnergies(
    method="demonstration values (not for scientific use)",
    li_ev_per_atom=-2.0,
    o2_raw_ev_per_molecule=-10.0,
    o2_correction_ev_per_molecule=0.0,
    bulk_litmo2_ev_per_formula_unit=-20.0,
)
dataframe = pd.DataFrame(
    {
        "Li": [4],
        "Ni": [4],
        "O": [8],
        "E": [-80.0],
        "a": [3.0],
        "b": [3.0],
        "gamma": [90.0],
    }
)
phases = PdData(dataframe, "Li", "O", references)
phases.standardize_pd_data()
energies = phases.get_surface_energy(
    V=np.array([0.0]),
    T=np.array([298.15]),
)
print(energies.shape)
print(bool(np.isfinite(energies).all()))

(1, 1)
True

The numerical references above are deliberately synthetic. Real calculations must use reference energies obtained with computational settings consistent with the slab energies, as described in Surface Phase Diagram Construction.