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, temperature=0, output='Phase_Diagram.png')[source]

Initialise the surface energy calculation.

Parameters:
  • data (list) – List of dictionaries for each phase
  • bulk (dictionary) – Dictionary containing data for bulk
  • deltaX (dictionary) – Range of chemical potential/label for species X
  • DeltaY (dictionary) – Range of chemical potential/label for species Y
  • x_energy (float) – DFT energy of adsorbing species
  • y_energy (float) – DFT energy of adsorbing species
  • temperature (int) – Temperature
  • output (str) – Output file name
Returns:

system – Plotting object
Return type:

class obj
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 (dic) – Dictonary of bulk properties
  • nspecies (int (optional)) – number of external species
  • check (bool (optional)) – 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 (dictionary) – Dictionary of 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 dictionaries for each phase
  • bulk (dictionary) – dictionary containing data for bulk
  • x (dictionary) – X axis chemical potential values
  • y (dictionary) – 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
surfinpy.mu_vs_mu.temperature_correction(nist_file, temperature)[source]

Use experimental data to correct the DFT free energy of an adsorbing species to a specific temperature.

Parameters:
  • nist_file (array like) – numpy array containing experiemntal data from NIST_JANAF
  • temperature (int) – Temperature to correct to
Returns:

gibbs – correct free energy
Return type:

float