plot

PdData class

class surface_pd.plot.PdData(dataframe: DataFrame, lithium_like_species: str, oxygen_like_species: str, reference_energies: ReferenceEnergies)

Own, normalize, and calculate one surface phase dataset.

Parameters:

• dataframe (pandas.DataFrame) – Phase rows containing atom counts, DFT energies, and in-plane lattice parameters. A defensive copy is stored; the caller’s dataframe is never mutated.

• lithium_like_species (str) – Column containing lithium-like species counts.

• oxygen_like_species (str) – Column containing oxygen-like species counts.

• reference_energies (ReferenceEnergies) – Validated user-provided Li, O2, and bulk LiTMO2 reference energies.

Raises:

• TypeError – If dataframe is not a pandas dataframe or reference_energies is not a ReferenceEnergies object.

• ValueError – If the lithium-like and oxygen-like column names are identical.

Notes

Call standardize_pd_data() before alignment or energy methods.

calculate_shift_energy(other: PdData) → float

Return the energy-density shift to add to other.

The selected phases must differ by a whole number of LiTMO2 formula units and represent the same relaxed surface-cell area within 0.5%.

Parameters:

other (PdData) – The second standardized dataset whose surface energies will be shifted.

Returns:

Constant shift in eV per square angstrom.

Return type:

float

Raises:

• TypeError – If other is not PdData.

• RuntimeError – If either dataset has not been standardized.

• ValueError – If reference energies, transition metals, surface areas, stoichiometry, or zero-energy masks are incompatible.

get_alignment_reference() → Series

Return one deterministic endpoint phase for dataset alignment.

For a fully lithiated maximum composition, the minimum Li/O endpoint is selected; otherwise the maximum Li/O endpoint is selected. Energy breaks composition ties, with the lowest-energy row returned.

Returns:

A copy of the selected standardized phase row.

Return type:

pandas.Series

get_surface_energy(V: ndarray, T: ndarray) → ndarray

Calculate surface energies over matching voltage/temperature meshes.

Parameters:

• V (array-like) – Voltage values in volts.

• T (array-like) – Absolute temperatures in kelvin, with the same shape as V.

Returns:

Surface energies in eV per square angstrom with shape (number_of_phases, *V.shape).

Return type:

numpy.ndarray

Raises:

• RuntimeError – If the dataset has not been standardized.

• ValueError – If V and T do not have identical shapes.

standardize_pd_data() → PdData

Validate and normalize phase rows to their maximum TM count.

Atom counts, DFT energy, and surface area are extensive quantities and are multiplied by the same row-specific factor. Area is scaled by changing b while keeping a and gamma fixed. Rows are sorted by oxygen-like and lithium-like counts in descending order.

Returns:

This instance, enabling explicit fluent use. Repeated calls are idempotent.

Return type:

PdData

property transition_metal: str

Return the detected transition-metal element symbol.

Raises:

RuntimeError – If the data has not yet been standardized.

ReferenceEnergies class

class surface_pd.plot.ReferenceEnergies(method: str, li_ev_per_atom: float, o2_raw_ev_per_molecule: float, o2_correction_ev_per_molecule: float, bulk_litmo2_ev_per_formula_unit: float)

Scientific reference energies supplied with phase-diagram data.

Parameters:

• method (str) – Free-text calculation-method provenance. The text is retained for auditing and is never interpreted as a lookup key.

• li_ev_per_atom (float) – Energy of the lithium reference in eV per atom.

• o2_raw_ev_per_molecule (float) – Raw energy of the oxygen reference in eV per O2 molecule.

• o2_correction_ev_per_molecule (float) – Explicit correction added to the raw oxygen energy, in eV per O2 molecule. Use zero when no correction is applied.

• bulk_litmo2_ev_per_formula_unit (float) – Bulk LiTMO2 energy in eV per formula unit.

Raises:

ValueError – If method is empty or contains a newline, or if an energy is not a finite real number. Boolean values are not accepted as energies.

property o2_ev_per_molecule: float

Return the corrected oxygen energy in eV per O2 molecule.

SurfaceEnergy class

class surface_pd.plot.SurfaceEnergy(V, T, nLi, nTM, nO, dft_energy, a, b, gamma, reference_energies)

Calculate the Gibbs free energy of one surface configuration.

Parameters:

• V (float or array-like) – Electrochemical potential in volts.

• T (float or array-like) – Absolute temperature in kelvin. Must be positive and broadcastable with V.

• nLi (float) – Number of lithium-like atoms in the slab model.

• nTM (float) – Number of transition-metal atoms in the slab model.

• nO (float) – Number of oxygen-like atoms in the slab model.

• dft_energy (float) – DFT total energy of the slab model in eV.

• a (float) – Positive first in-plane lattice length in angstroms.

• b (float) – Positive second in-plane lattice length in angstroms.

• gamma (float) – Angle between a and b in degrees, strictly between 0 and 180.

• reference_energies (ReferenceEnergies) – Validated Li, O2, and bulk LiTMO2 reference energies.

Raises:

TypeError – If reference_energies is not a ReferenceEnergies object.

Notes

The constructor stores inputs without validating geometric or atom-count domains. g_oxygen() validates temperature when energy is evaluated.

g_oxygen()

Return the temperature-dependent oxygen chemical potential.

The DFT reference is combined with ideal-gas enthalpy and entropy corrections at standard pressure. Molar thermal corrections are converted from kJ/mol to eV before being added to the DFT energy.

Returns:

Oxygen chemical potential in eV per O atom. The result has the same shape as T; scalar input produces a NumPy scalar.

Return type:

numpy.ndarray or numpy.float64

Raises:

ValueError – If any absolute temperature is zero or negative.

Notes

Pressure dependence is neglected. The reference temperature is 298.15 K, and the standard-state O2 entropy and 0-to-298.15 K enthalpy increment are taken from NIST-JANAF thermochemical data.

get_gibbs_free_energy()

Calculate the surface Gibbs free energy.

Returns:

Surface Gibbs free energy in eV per square angstrom. The result follows the broadcast shape of V and T.

Return type:

numpy.ndarray or numpy.float64

Notes

The energy is divided by twice the in-plane area, corresponding to the two equivalent surfaces of a symmetric slab model.