hori package

Submodules

hori.common module

Contains common elements, such as reference energies.

hori.common.calculate_reference_energy(formula)

For a formula, such as CH2OH, counts the atoms and makes a reference energy (eV) based on the atomic energies in reference_energies.

Parameters:formula (string) –

hori.common.countatoms(formula)

Given an atomic formula, e.g. CH2O, returns a dictionary of atomic counts, e.g, d = {‘C’:1,’H’:2,’O’:1}.

Parameters:formula (string) –

hori.common.create_full_pathway()

Returns the full CO2 reduction pathway that I have commonly looked at.

hori.common.hbond_dict()

Returns a dictionary of hydrogen bond stabilizations, in eV.

hori.common.hbond_dict_none()

Returns a dictionary of hydrogen bond stabilizations, in eV.

hori.common.reference_energies = {'H': -16.01475, 'C': -155.456, 'O': -437.7214}

For convenience, all of the surfaces which have calculations are listed in all_surfaces.

hori.io module

Functions to read in or write out data.

hori.io.atomsfromlist(atomslist)

Takes in a list of atomic symbols and coordinates, as in [atom1, atom2, ...] where atomX = (symbol, (x,y,z)), and symbol is the atomic symbol (e.g. “Na”) and x,y,z is the position, in Angstroms, of the atom. Returns an ASE atoms object.

hori.io.electronicenergy(surface, adsorbate=None, verbose=True)

Reads in the electronic energy from the calculated data set. If the adsorbate is None or ‘’, then returns the energy of the clean slab, if the energy doesn’t exist in the data set, then returns nan. Alerts the user to this fact if verbose=True.

hori.io.gasdata(species)

Reads in the electronic energy and vibrations from the calculated data set.

hori.io.genericvibrations(adsorbate)

Reads in the generic vibrations used for adsorbates in general.

hori.io.get_directory()

Returns the internal value of datapath.

hori.io.ignoreimaginaryvibrations(adsorbate)

Reads in the generic vibrations used for adsorbates in general. Calculates only real part.

hori.io.set_directory(path)

Use to set a directory of pickle files other than the current. The directory specified must have subdirectories ‘electronic-energies’, and/or ‘generic-vibrations’, depending on the data to be accessed.

hori.io.specificvibrations(adsorbate, surface)

Reads in the vibrations for an adsorbate on a specific surface.

hori.pathway module

Contains functions to calculate the change in free energy along the CO2 reduction pathway.

class hori.pathway.Pathway(startingstep='1', startingenergy=0.0)

Class to hold pathway and connectivity information, and to calculate the free energies along that pathway given binding (free) energies and chemical potentials. After initializing, add steps to the pathway with the add_step function.

Parameters:

• startingstep (str, optional) –
• startingenergy (float, optional) –

addstep(first, second, list)

Method to add a step to the pathway between the first and second states. Call this method with the state names and the list of changes between them. E.g., if state ‘1’ to state ‘5’ is:

* + CO2 + (H+ + e-) -> *COOH

then use this method with first=‘1’,second=‘5’, and list = [‘-s’, ‘-CO2’, ‘-pe’, ‘+a_COOH’]. In the list, reactants are preceded with a - and products with a +. Following the +/- is:

s : bare surface
pe : proton-electron pair
a_<chemical formula> : adsorbate
<chemical formula> : non-adsorbed species

where the <>’s are left off the chemical formula. The info is

sanity checked and added to an internal list of the form:

[ [firststate,secondstate,reaction], ... ]

Parameters:

• first (string) –
• second (string) –
• list (list) –

Raises:

RuntimeError

calculate_Gs(BG, mu, mu_pe)

Calculates the free energy along every step in the pathway, and returns this as a dictionary. Also store it in self.G. Takes as input BG, which is a dictionary of adsorbate free energies, mu, which is a dictionary of gas free energies, and mu_pe which is the free energy of a proton-electron pair (the last is a float, not a dictionary). These are usually taken from

Parameters:

• BG (hori.thermo.AdsorbateThermodynamics.G) –
• mu (hori.thermo.GasThermodynamics.G) –
• mu_pe (hori.thermo.ProtonElectronThermodynamics.G) –

Raises:

RuntimeError

find_limiting_potential(path=None)

Uses the current values of the the free energy (stored in self.G; run self.calculate_Gs() first with mu_pe set to 0 V to establish this) to find the limiting potential and the step that limits the potential. This is defined as the largest uphill step – after this is overcome, the pathway will be downhill.

If the pathway is branched, then the path must be specified,

similar to:

path = [‘1’,‘28’,‘4’]

Parameters:path (list, optional) – Raises:RuntimeError

hori.pathway.calculate_rxn_deltaG(rxn, BG, mu, mu_pe)

Calculates delta-G of reaction for the reaction listed in rxn, given dictionaries of binding free energy (BG) and non-adsorbed species chemical potential (mu), as well as the chemical potential of a proton- electron pair at the current voltage (and pH, if applicable). rxn is in the format created by Pathway.addstep(). Note that in general, BG[‘’] will need to be defined; this is the clean slab’s binding energy, which may be 0. or may be a large number, depending on the reference state chosen.

Parameters:

• rxn (list) –
• BG (hori.thermo.AdsorbateThermodynamics.G) –
• mu (hori.thermo.GasThermodynamics.G) –
• mu_pe (hori.thermo.ProtonElectronThermodynamics.G) –

hori.pathway.step2string(rxn)

Convert reaction step (as used in pathway) to a string.

Parameters:rxn (list) – Description

hori.plots module

class hori.plots.PlotStates(ax, G, halfwidth, textwidth, fontsize, color, textcolor, dashcolor, textposition='inline', text_vspace=0.0, lw=2.0)

Functions to update existing plots with energy levels and connectors. Initialize as

PlotStates(ax,G,halfwidth,textwidth,fontsize,color,textposition, text_vspace)

connect(state1, zone1, state2, zone2, lw=1.0, barrier=0, linestyle='-')

Draws a dashed connector between stated positions and energies. Looks up the energies in the G dictionary. state1 and state2 should be fed in as strings. zone1 and zone2 should be fed in as numbers.

Parameters:

• state1 (string) –
• zone1 (int) –
• state2 (string) –
• zone2 (int) –
• lw (float, optional) –
• barrier (int, optional) –
• linestyle (str, optional) –

plotstate(state, zone, label=None, special_text_vspace=None, special_color=None)

Plots a horizontal line at the specified energy state. Pulls the energy from the G dictionary. State should be fed in as a string. zone is the zone number in which to plot it. This is generally the total number of electrons transferred to get to the state. zone should be fed in as a number (probably an integer). By default, puts a text label of the state (number) on the bar, but an alternate label can be fed in via the label keyword.

Parameters:

• state (string) –
• zone (int) –
• label (string, optional) –
• special_text_vspace (float, optional) –
• special_color (string, optional) –

hori.plots.scatter_plot_from_dict(ax, dict1, dict2, keys='auto')

Function designed to take two dictionaries and convert them into a plot, where both dictionaries have the form dict[key] = value. This will make a plot of the values at all points where the dictionaries have common keys and add them to the axis object ax.

Parameters:

• ax (ax object) –
• dict1 (dict) –
• dict2 (dict) –
• keys (list, optional) –

hori.thermo module

class hori.thermo.AdsorbateThermodynamics(ads_list, temperature, hbond_dict=None, vibrationsmode=None, surface=None)

Class that loads adsorbate free energy data for a list of adsorbates and has methods to report back thermodynamic properties of the list as a function of the temperature and the electronic energy (without needing to re-access the data stored on disk). Initialize with ads_list, which is a list in one of two formats. It is either a list of the adsorbate names, e.g.,

[‘CHO’, ‘COOH’, ‘CO’]

or a list of adsorbates and a vibration mode:

[[‘CHO’, ‘generic’], [‘COOH’, ‘specific’], [‘CO’, ‘auto’],]

where ‘generic’ means it will calculate vibrations using the vibrations in the generic folder, ‘specific’ means it will use the specific vibrations for that adsorbate on the specified surface (and exit with an error if it is missing) and ‘auto’ means it will attempt to use ‘specific’ vibrations, but will use ‘generic’ in each instance that the ‘specific’ vibration is not available. If the first input form is used, then the vibrations mode is set with the ‘vibrationsmode’ keyword, which defaults to ‘auto’. For brevity the numbers 0, 1, and 2 can be used for ‘generic’, ‘specific’, and ‘auto’, respectively.

The adsorbate name should be something like ‘COOH’. Use ‘’ to indicate the clean slab. The other inputs are the temperature (in K) and a dictionary of hydrogen-bond stabilizations by the water overlayer, of the form hbond_dict[adsorbate] = float (in eV).

When this class has all needed info it auto-calculates. When changing an electronic energy or the temperature, the class auto-recalculates, so a free energy can just be pulled with self.G[ads].

If other properties are needed (mainly the electronic energy), they can be accessed in self.data[ads].

Parameters:

• ads_list (list) –
• temperature (float) –
• hbond_dict (dict, optional) –
• vibrationsmode (string, optional) –
• surface (string, optional) –

Raises:

RuntimeError

print_thermodynamic_contributions(ads_list='all')

Prints the contributions to U,S,G for each adsorbate in ads_list at the current conditions. If gas_list is ‘all’, then prints for all gases. Note that this forces a re-calculation – if any parameters have changed, then what is reported will be for those new values.

Parameters:ads_list (list, optional) –

recalculate(force=False)

Calculates free energy information only when things have changed and the data (i.e., vibrations) exist. If force is True, then it will recalculate everything regardless of changes.

Parameters:force (bool, optional) –

set_electronic_energy(adsorbate, elec_energy)

Sets the electronic energy (eV) for the specified adsorbate and re-calculates G based only on that change (doesn’t trigger a global recalculate).

Parameters:

• adsorbate (string) –
• elec_energy (float) –

set_energies_by_metal(metal)

Legacy function – use set_surface.

Parameters:metal (string) –

set_surface(surface)

Looks up the electronic energies, and, if specified in vibrequest, vibrations, for each adsorbate on the surface specified using the io functions of the hori module, assigns them, and re-calculates G.

Parameters:surface (string) –

set_temperature(temperature)

Sets the temperature (K) for adsorbate free energy calcs.

Parameters:temperature (float) –

class hori.thermo.GasThermodynamics(gas_list, functional)

Class that loads gas chemical potential data for a list of gases, and has methods to report back thermodynamic properties of the list of gases as a function of temperature and fugacity (without needing to re-access the data stored on disk.

Initialize with gas_list, which is a list of gases and their corresponding temperature and pressure (fugacity), of the form:

[ [gas_name, temperature, fugacity], ... ]

After instantiating this class or changing a temperature or pressure, this class auto-recalculates, so a free energy can just be pulled with self.G[gas]

Parameters:

• gas_list (list) –
• functional (string) –

Raises:

RuntimeError

print_thermodynamic_contributions(gas_list='all')

Prints the contributions to H,S,G for each gas in gas_list at the current conditions. If gas_list is ‘all’, then prints for all gases.

Parameters:gas_list (list, optional) –

set_all_fugacities(fugacity)

Set the fugacity of all gases to the same value.

Parameters:fugacity (float) –

set_all_temperatures(temperature)

Set the temperature of all gases to the same value.

Parameters:temperature (float) –

set_gas_fugacity(gas, fugacity)

Change the fugacity of an individual gas.

Parameters:

• gas (string) –
• fugacity (float) –

set_gas_temperature(gas, temperature)

Change the temperature of an individual gas.

Parameters:

• gas (string) –
• temperature (float) –

class hori.thermo.ProtonElectronThermodynamics(temperature, voltage, functional)

Class that loads the chemical potential data for the proton-electron pair in the Computational Hydrogen Electrode model, meaning that it uses the thermodynamic properties of H2 gas at 1 atm and adjusts them for temperature and voltage. In this module, the voltage is verus RHE, so a pH correction is not needed.

Instantiate with the temperature and voltage, and the chemical potential of the proton-electron pair is automatically calculated and stored in self.G. Similarly, after changing the temperature or voltage with the .set_temperature or .set_voltage method, self.G is auto-recalculated.

Temperature is in K and voltage is in V vs RHE.

Parameters:

• temperature (float) –
• voltage (float) –
• functional (string) – exchange-correlation functional

set_temperature(temperature)

Change the temperature (K).

set_voltage(voltage)

Change the potential (V vs RHE).

hori.thermo.gas_chemical_potential(species, temperature, fugacity)

For a gas, given its temperature (K) and fugacity (Pa), returns its chemical potential.

Parameters:

• species (string) –
• temperature (float) –
• fugacity (float) –

Raises:

RuntimeError