surfinpy.mu_vs_mu¶

Functions related to the generation of surface phase diagrams as a function of chemical potential. An explanation of theory can be found here

surfinpy.mu_vs_mu.calculate(data, bulk, deltaX, deltaY, x_energy=0, y_energy=0, increments=0.025)[source]¶

Initialise the surface energy calculation.

Parameters

data (list) – List of surfinpy.data.DataSet for each phase
bulk (surfinpy.data.ReferenceDataSet) – Data for bulk
deltaX (dict) – Range of chemical potential/label for species X
DeltaY (dict) – Range of chemical potential/label for species Y
x_energy (float) – DFT energy of adsorbing species
y_energy (float) – DFT energy of adsorbing species

Returns

system – Plotting object

Return type

surfinpy.plotting.ChemicalPotentialPlot

surfinpy.mu_vs_mu.calculate_excess(adsorbant, slab_cations, area, bulk, nspecies=1, check=False)[source]¶

Calculates the excess of a given species at the surface. Depending on the nature of the species, there are two ways to do this. If the species is a constituent part of the surface, e.g. Oxygen in $TiO_2$ then the calculation must account for the stoichiometry of that material. Using the $TiO_2$ example

$\Gamma_O = \frac{1}{2A} \Bigg( nO_{Slab} - \frac{nO_{Bulk}} {nTi_{Bulk}}nTi_{Slab} \Bigg)$

where $nO_{Slab}$ is the number of oxygen in the slab, $nO_{Bulk}$ is the number of oxygen in the bulk, A is the surface area, $nTi_{Bulk}$ is the number of Ti in the bulk and $nTi_{Slab}$ is the number of Ti in the slab. If the species is just an external adsorbant, e.g. water or carbon dioxide then one does not need to consider the state of the surface, as there was none there to begin with.

$\Gamma_{H_2O} = \frac{nH_2O}{2A}$

where $nH_2O$ is the number of water molecules and A is the surface area.

Parameters

adsorbant (int) – Number of species
slab_cations (int) – Number of cations
area (float) – Area of surface
bulk (dict) – Dictonary of bulk properties
nspecies (int) – number of external species
check (bool) – Check if this is an external or constituent species.

Returns

Surface excess of given species.

Return type

float

surfinpy.mu_vs_mu.calculate_normalisation(slab_energy, slab_cations, bulk, area)[source]¶

Normalises the slab energy relative to the bulk material. Thus allowing the different slab calculations to be compared.

$Energy = \frac{1}{2A} \Bigg( E_{MO}^{slab} - \frac{nCat_{slab}}{nCat_{Bulk}} E_{MO}^{Bulk} \Bigg)$

where Energy is the slab energy normalised to the bulk, $E_{MO}^{slab}$ is the DFT slab energy, $nCat_{slab}$

is the number of slab cations, $nCat_{Bulk}$ is the number of bulk

cations, $E_{MO}^{Bulk}$ is the DFT bulk energy A is the surface area.

Parameters

slab_energy (float) – Energy of the slab from DFT
slab_cations (int) – Total number of cations in the slab
bulk (surfinpy.data.DataSet) – Bulk properties
area (float) – Surface area

Returns

Constant normalising the slab energy to the bulk energy.

Return type

float

surfinpy.mu_vs_mu.calculate_surface_energy(deltamux, deltamuy, x_energy, y_energy, xexcess, yexcess, normalised_bulk)[source]¶

Calculates the surface for a given chemical potential of species x and species y for a single phase.

$\gamma_{Surf} = \frac{1}{2S} \Bigg( E_{MO}^{slab} - \frac{nCat_{Slab}}{nCat_{Bulk}} E_{MO}^{Bulk} \Bigg) - \Gamma_O \mu_O - \Gamma_{H_2O} \mu_{H_2O} - \Gamma_O \mu_O (T) - \Gamma_{H_2O} \mu_{H_2O} (T)$

where S is the surface area, $E_{MO}^{slab}$ is the DFT energy of the stoichiometric slab, $nCat_{Slab}$ is the number of cations in the slab, $nCat_{Slab}$ is the number of cations in the bulk unit cell, $E_{MO}^{Bulk}$ is the DFT energy of the bulk unit cell, $\Gamma_O$ $\Gamma_{H_2O}$ is the excess oxygen / water at the surface and $\mu_O$ $\mu_{H_2O}$ is the oxygen / water chemcial potential.

Parameters

deltamux (array_like) – Chemical potential of species x
deltamuy (array_like) – Chemical potential of species y
x_energy (float) – DFT energy or temperature corrected DFT energy
y_energy (float) – DFT energy or temperature corrected DFT energy
xexcess (float) – Surface excess of species x
yexcess (float) – Surface excess of species y
normalised_bulk (float) – Slab energy normalised to the bulk value.

Returns

2D array of surface energies as a function of chemical potential of x and y

Return type

array_like

surfinpy.mu_vs_mu.evaluate_phases(data, bulk, x, y, nsurfaces, x_energy, y_energy)[source]¶

Calculates the surface energies of each phase as a function of chemical potential of x and y. Then uses this data to evaluate which phase is most stable at that x/y chemical potential cross section.

Parameters

data (list) – List containing the surfinpy.data.DataSet for each phase
bulk (surfinpy.data.DataSet) – Data for bulk
x (dict) – X axis chemical potential values
y (dict) – Y axis chemical potential values
nsurfaces (int) – Number of phases
x_energy (float) – DFT 0K energy for species x
y_energy (float) – DFT 0K energy for species y

Returns

phase_data – array of ints, with each int corresponding to a phase.

Return type

array_like