pdos_overlap

The get_adsorbate_indices function

get_adsorbate_indices(GAS_CONTCAR, ADSORBATE_CONTCAR)[source]

Identify the adsorbate and adsorption site indices

Parameters

  • GAS_CONTCAR (str) – Location to VASP CONTCAR file for a gas molecule.

  • ADSORBATE_CONTCAR (str) – Location to VASP CONTCAR file for an adsorbate + surface

Returns

  • adsorbate_indices (list[int]) – Index (indices) of adsorbate atom(s) in REFERENCE_PDOS. Obtained from pdos_overlap.get_adsorbate_indices.

  • site_indices (list[int]) – Index (indices) of adsorbation site atom(s) in REFERENCE_PDOS. Obtained from pdos_overlap.get_adsorbate_indices.

The PDOS_OVERLAP class

class PDOS_OVERLAP(GAS_PDOS, REFERENCE_PDOS, adsorbate_indices, site_indices, min_occupation=0.9, upshift=4.5, energy_weight=3, sum_density=False, sum_spin=True)[source]

Class for calculating adsorbate-surface relative energy overlap

Parameters

  • GAS_PDOS (vasp_dos.VASP_DOS) – VASP_DOS object of gas phase calculation of adsorbate.

  • REFERENCE_PDOS (vasp_dos.VASP_DOS) – VASP_DOS object of reference adsorbate+surface system.

  • adsorbate_indices (list[int]) – Index (indices) of adsorbate atom(s) in REFERENCE_PDOS. Obtained from pdos_overlap.get_adsorbate_indices.

  • site_indices (list[int]) – Index (indices) of adsorbation site atom(s) in REFERENCE_PDOS. Obtained from pdos_overlap.get_adsorbate_indices.

  • min_occupation (float) – Minimum state occupation for a section of density to be considered a molecular orbital.

  • upshift (float) – The energy the gas molecular orbitals are shifted before pairing

  • energy_weight (float) – The degree to weight the energy error before computing the associated liklihood that goes into computing the scores. Increasing the energy weight sharpens the univariate distribution around matching peak positions.

  • sum_density (bool) – Tag indicates if state density on the same sublevel should be summed when calculating overlap of the site atomic orbitals and the adsorbate molecular orbitals.

  • sum_spin (bool) – Tag indictes if state density with different spins should be summed when generating gas and adsorbate orbital features.

Variables

  • gas_indices (list[ing]) – Atom index (indices) of the gas molecule.

  • gas_features (numpy.ndarray) – gas molecular orbital features used in matching gas and adsorbate molecular orbitals

  • adsorbate_features (numpy.ndarray) – Adsorbate molecular orbital features used in matching gas and adsorbate molecular orbitals

  • gas_orbitals (numpy.ndarray) – Length mxn array where m is the number of molecular orbitals and n is equal to GAS_PDOS.ndos (dos discritizations)

  • gas_occupations (numpy.ndarray) – Integrated state density of each gas orbital.

  • adsorbate_orbitals (numpy.ndarray) – Length mxn array where m is the number of adsorbate orbitals and n is equal to REFERENCE_PDOS.ndos (dos discritizations)

  • adsorbate_occupations (numpy.ndarray) – Integrated state density of each adsorbate molecular orbital.

  • orbital_scores (numpy.ndarray) – Array of size mxn where m and n are the number of gas and adsorbate molecular orbitals respecitvely. Indicates similarity. If the number of gas orbitals equals the number of adsorbate orbitals then the scores are orbital-pairing scores.

  • feature_type (str) – Indicates whether integrated state density of atomic orbitals are used for molecular orbital features or if molecular orbital occupation fractions.

  • gas_orbital_indices (list) – List of vector indices that aportion the gas molecule energy and projected density into molecular orbitals

  • adsorbate_orbital_indices (list) – List of vector indices that aportion the adsorbate molecule energy and projected density into molecular orbitals

  • gas_band_centers (numpy.ndarray) – Gas molecular orbital band centers

  • adsorbate_band_centers (numpy.ndarray) – Adsorbate molecular orbital band centers

  • gas_2_adsorbate (numpy.ndarray) – Array of gas and adsorbate orbital indices along with corresponding band centers

Notes

GAS_PDOS is used to determine the number of molecular orbitals that can interact with the surface and to calculate relative pdos overlap the with projected density of adsorption sites without adsorbates.

REFERENCE_PDOS is used to determine which metal states, projected onto atomic orbitals, will interact with the adsorbate/gas molecular orbitals.

All parameters are saved as attributes.

Methods

_assign_orbitals(orbital_scores)[source]

Assign gas orbitals to one or more adsorbate orbitals

Parameters

orbital_scores (numpy.ndarray) – M x N 2D array where M is the number of gas molecular orbitals and N is the number of adsorbate molecular orbitals

Returns

gas_2_adsorbate – Array of gas and adsorbate orbital indices along with corresponding band centers

Return type

numpy.ndarray

_get_mol_orbitals(PDOS, atom_indices)[source]

Molecular orbitals as an M x ndos array

Parameters

  • PDOS (vasp_dos.VASP_DOS) – VASP_DOS object of gas or surface phase calculation of adsorbate

  • atom_indices (list[int]) – indices of atoms to include in the TOTAL DOS. If empty, then all atoms are included (as for the gas)

Returns

  • peak_energies (float or numpy.ndarray) – peak energy(s) of molecular orbital(s)

  • peak_densities (float or numpy.ndarray) – peak density(ies) of molecular orbital(s)

  • mol_orbitals (numpy.ndarray) – M x ndos 2D array where M is the number of molecular orbitals and ndos is the number of gridpoints for the density of states

  • orbital_indices (list[numpy.ndarray]) – Length M list of non-zero orbital indices

_get_orbital_features(PDOS, orbital_indices, atom_indices, upshift)[source]

Molecular orbitals as an M x ndos array

Parameters

  • PDOS (vasp_dos.VASP_DOS) – VASP_DOS object of gas or surface phase calculation of adsorbate

  • orbital_indices (list[numpy.ndarray]) – Length M list of non-zero orbital indices

  • atom_indices (list[int]) – indices of atoms to include in the TOTAL PDOS.

  • upshift (float) – The energy the gas molecular orbitals are shifted before pairing

Returns

orbital_features – M x n_features 2D array where M is the number of molecular orbitals and n_features is the number of orbital features for calculating orbital similarity. Includes molecular orbital energy center and integrated s, p, and d molecular orbital density of states

Return type

numpy.ndarray

static _get_orbital_scores(reference_features, comparison_features, energy_weight=3)[source]

Orbital scores given reference and comparision features

Parameters

  • reference_features (numpy.ndarray) – Reference features of molecular orbitals whose values are treated as the mean

  • comparison_features (numpy.ndarray) – Comparison features that are treated as perturbations from the reference features for generating probabilities

  • energy_weight (float) – The degree to weight the energy error before computing the associated liklihood that goes into computing the scores. Increasing the energy weight sharpens the univariate distribution around matching peak positions.

Returns

orbital_scores – M x N 2D array where M is the number of reference orbitals and N is the number of comparison orbitals

Return type

numpy.ndarray

static _get_sum_score(orbital_scores)[source]

Compute sum for optimizing upshift

Parameters

orbital_scores (numpy.ndarray) – M x N 2D array where M is the number of gas molecular orbitals and N is the number of adsorbate molecular orbitals

Returns

sum_score – Sum of highest scores for each gas or adsorbate molecular orbital

Return type

numpy.ndarray

_get_upshift_score(upshift)[source]

Obtain orbital scores given an upshift value

Parameters

upshift (float) – The energy the gas molecular orbitals are shifted before pairing

Returns

sum_score – Sum of highest scores for each gas or adsorbate molecular orbital

Return type

numpy.ndarray

get_energy_overlap(atomic_orbitals, sum_overlap=False, sum_spin=True, normalize=False)[source]

Calculate energy overlap of molecular orbitals with atomic orbitals

Parameters

  • atomic_orbitals (list[str]) – Adsorption site atomic orbitals of interest.

  • sum_density (bool) – Tag indicates if overlap of the site atomic orbitals and the adsorbate molecular orbitals shold be summed for overlap of atomic orbitals in the same sublevel.

  • sum_spin (bool) – Tag indictes if state density with different spins should be summed when generating gas and adsorbate orbital features.

  • normalize (bool) – Tag indicates if energy overlap should be normalized.

Returns

  • overlap_orbitals (list[str]) – List of atomic orbitals for which overlap energies of the adsorbate state with the metal adsorption-site states are calculated.

  • energy_overlap (numpy.ndarray) – Array of shape nxp where n is the number of adsorbate molecular orbitals and p is the number of adsorption-site atomic orbitals. Elements are the projected density of states overlap integral of an adsorption site states (projected onto atomic orbitals), and the adsorbate states (projected and summed into molecular orbitals)

Notes

As implemented, molecular_orbitals are for the adsorbate and PDOS is for some surface.

get_orbital_interaction(orbital_index, PDOS, site_indices, atomic_orbitals, BULK_PDOS, bulk_atom=0, sum_interaction=False, sum_spin=True, method='orbital_bond_energy', use_orbital_proximity=False, index_type='gas')[source]

Calculate surface and gas orbital interactions

Parameters

  • orbital_index (int) – Identifies the gas/adsorbate orbital with which to calculate the overlap of the PDOS atomic orbitals

  • PDOS (vasp_dos.VASP_DOS) – VASP_DOS object of surface phase calculation of adsorbate

  • overlap_orbitals (list[str]) – List of atomic orbitals for which overlap energies of the gas state with a metal adsorption-site states are calculated.

  • site_indices (list[int]) – indices of atoms to include in the TOTAL DOS.

  • atomic_orbitals (list[str]) – Adsorption site atomic orbitals of interest.

  • sum_interaction (bool) – Tag indicates if interactions of molecular orbitals with atomic orbitals on the same sublevel should be summed

  • sum_spin (bool) – Tag indictes if state density with different spins should be summed when generating gas and adsorbate orbital features.

  • method (str) – Can be ‘orbital_bond_energy’ or ‘band_width’ and dictates whate values from the pdos are used in computing relative potential to bond

  • use_orbital_proximity (bool) – Indicates whether proximity of the surface to the gas states should be used to scale interactions. Only used if index_type = ‘gas’

  • index_type (str) – ‘gas’ or ‘adsorbate’ identifies whether the orbital indices are for the gs or adsorbate orbitals

Returns

orbital_interaction – Metal atomic orbital interactions with the gas molecular orbitals

Return type

numpy.ndarray

get_orbital_scores(gas_features, adsorbate_features, energy_weight)[source]

Select the set of orbital scores to be used

Parameters

  • gas_orbital_features (numpy.ndarray) – gas orbital features

  • adsorbate_orbital_features (numpy.ndarray) – adsorbate orbital features

  • energy_weight (float) – The degree to weight the energy error before computing the associated liklihood that goes into computing the scores. Increasing the energy weight sharpens the univariate distribution around matching peak positions.

Returns

orbital_scores – M x N 2D array where M is the number of gas molecular orbitals and N is the number of adsorbate molecular orbitals

Return type

numpy.ndarray

static get_pair_scores(orbital_scores, max_iterations=500, verbose=False)[source]

Get normalized pair scores using matrix scaling

Parameters

  • orbital_scores (numpy.ndarray) – M x M 2D array

  • max_iterations (int) – Maximum number of iterations before ending normalization procedure

  • verbose (bool) – Print completion information

Returns

orbital_scores – M x M 2D array normalized symmetric matrix.

Return type

numpy.ndarray

Notes

Matrix scaling perfomed using RAS method described in DOI: 10.1109/FOCS.2017.87

optimize_energy_shift(bound=- 0.5, 1.5, reset=False, plot=False)[source]

Get the optimal energy shift in the gas and adsorbate orbitals

Parameters

  • upshift (float) – The energy the gas molecular orbitals are shifted before pairing

  • bound (tuple) – Lower and upper bounds to for which to find the optimal energy shift

  • rest (bool) – Indicates whether the values contained in the PDOS_OVERLAP object should be reset using the optimal energy shift

  • plot (bool) – Indicates whether optimization results should be plotted

Returns

optimized_upshift – The fraction of the fermi energy the gas and adsorbate molecular orbitals are shifted before pairing for maximizing likelihood of score pairings

Return type

float

plot_energy_overlap(indices=[Ellipsis], atomic_orbitals=['s', 'p', 'd'], sum_overlap=False, figure_directory='print', extension='jpg')[source]

Plot energy overlap of atomic and molecular orbitals

Parameters

  • indices (list[int]) – Index values of adsorbate molecular orbitals for which to plot energy overlap histograms.

  • figure_directory (str) – indicates how to display or save the figures or directory to save

  • atomic_orbitals (list[str]) – Adsorption site atomic orbitals of interest.

  • extension (str) – ‘pdf’ or ‘jpg’ how to save the file

plot_projected_density(sum_density=True, sum_spin=True, figure_directory='print', extension='jpg')[source]

Plot projected density of the gas, adsorbate and site

Parameters

  • sum_density (bool) – Tag indicates if state density on the same sublevel should be summed when calculating overlap of the site atomic orbitals and the adsorbate molecular orbitals.

  • sum_spin (bool) – Tag indictes if state density with different spins should be summed when generating gas and adsorbate orbital features.

  • figure_directory (str) – indicates how to display or save the figures

  • extension (str) – ‘pdf’ or ‘jpg’ how to save the file