PourPy.system

Created on Mon Jul 24 09:50:23 2023

@author: fabioenricofurcas

Attributes

element_list

Classes

`Reaction`	Reaction class featuring all reaction-specific parameters of the (electro)chemical reactions to be included in the Pourbaix diagram.
`Reactant`	Reactant class that defines an ion, compound or electron including all required thermodynamic and molecular parameters.
`Constants`	Convert a string or number to a floating point number, if possible.
`State`	Create a collection of name/value pairs.
`Defaults`
`System`	System class that contains all required physiochemical parameters, elements and reacion constituents nessecary to create a pourbaix diagram.

Module Contents

class PourPy.system.Reaction(constituents, system)

Bases: object

Reaction class featuring all reaction-specific parameters of the (electro)chemical reactions to be included in the Pourbaix diagram.

__str__()

Return the string representation of the reaction, where all reactants appear on the left hand side and all products appear on the right of the reacton arrow.

Returns:: A string representation of the reaction, e.g., ‘H2O ⇄ H2 + 0.5*O2’.
Return type:: str

initialize()

Initialize the Reaction object by calculating various reaction-specific properties.

Returns:: None
Return type:: None

_get_reaction_string()

Create the string representation of the reaction, where all reactants appear on the left hand side and all products appear on the right of the reacton arrow.

Returns the string representation of the reaction, e.g., ‘H2O ⇄ H2 + O2’.

Returns:: A string representation of the reaction.
Return type:: str

_get_echem_reaction()

Checks if the reaction is an electrochemical reaction, i.e. whether it contains electrons, and returns True if it’s electrochemical, otherwise returns False.

Returns:: True if the reaction is electrochemical, False otherwise.
Return type:: bool

_get_pH_reaction()

Checks if the reaction is a pH-dependent reaction, i.e. whether it contains protons, and returns True if it’s pH-dependent, otherwise returns False.

Returns:: True if the reaction is pH-dependent, False otherwise.
Return type:: bool

property dGr: float

Calculate the standard Gibbs free energy change of the reaction from the standard molar Gibbs free energies of all reation costituents.

Returns:: The standard Gibbs free energy change of the reaction in joules per mole.
Return type:: float

property dHr: float

Calculate the standard enthalpy change of the reaction from the standard molar enthalpies of all reation costituents.

Returns:: The standard enthalpy change of the reaction in joules per mole.
Return type:: float

property dSr: float

Calculate the standard entropy change of the reaction from the standard Gibbs free energy and enthalpy.

Returns:: The standard entropy change of the reaction in joules per mole per degrees kelvin.
Return type:: float

property K

Calculate the equilibrium constant for the reaction from its standard Gibbs free energy.

Returns:: The equilibrium constant K for the reaction.
Return type:: float

property E0

Calculate the standard electrode potential for the reaction in volts vs. SHE from its standard Gibbs gree energy.

Returns:: The standard electrode potential E0 for the electrochemical reaction in volts vs. SHE, or 0 if the reaction is not an electrochemical reaction.
Return type:: float

property nElectrons

Retrieve the number of electrons involved in the reaction.

Returns:: The number of electrons involved in the electrochemical reaction, or 0 if the reaction is not an electrochemical reaction.
Return type:: float

property nProtons

Retrieve the number of protons involved in the reaction.

Returns:: The number of protons involved in the pH-dependent reaction, or 0 if the reaction is not pH-dependent.
Return type:: float

_get_Hlimit()

Retrieve the range of H+ activities corresponding to the pH limits of the Pourbaix diagram.

Returns:: An array of H+ activities.
Return type:: numpy.ndarray

property Q: float

Calculate the reaction quotient Q for the reaction.

Returns:: The reaction quotient Q for the reaction.
Return type:: float

property rQ: float

Calculate the reduced reaction quotient rQ excluding the activity contribution of protons.

Returns:: The reduced reaction quotient rQ for the reaction.
Return type:: float

property QpH: list

Calculate reaction quotient of the reaction at different H+ activities.

Returns:: A list of reaction quotients at different H+ ion concentrations.
Return type:: list

_get_pourbaixLine()

Calculate the Pourbaix line formulated by the reaction.

Returns:: A list of coordinates defining the Pourbaix line, depending on whether the reaction is potential- and/or pH-dependent.
Return type:: list
Raises:: ValueError – If the reaction is neither potential- nor pH-dependent.

_sanity_check()

Perform a sanity check on the total charge and atom balance of all species in the reaction.

Returns:: A message indicating whether charge and atom balances are correct or if there’s a warning.
Return type:: str

_balanced_charge()

Check if the reaction is charge-balanced.

Returns:: True if the reaction’s charge is balanced, False otherwise.
Return type:: bool

_balanced_atoms()

Check if the reaction has balanced numbers of atoms of each chemical element.

Returns:: True if the reaction’s atoms are balanced, False otherwise.
Return type:: bool

class PourPy.system.Reactant(formula, state, dGf, dHf, Sm, elements)

Reactant class that defines an ion, compound or electron including all required thermodynamic and molecular parameters.

__str__(): Return str(self).

initialize()

Initialize additional properties of the Reactant.

Returns:: None
Return type:: None

_get_formula(formula)

Validate and returns user-input chemical formula of the reactant.

Parameters:: formula – The chemical formula to validate.
Returns:: Validated chemical formula.

_get_state(state)

Validates and returns the user-input physical state of the reactant.

Parameters:: state – The physical state to validate.
Returns:: Validated physical state.

_get_charge()

Validates and returns the user-input charge of the reactant.

Returns:: The charge of the reactant, 0 if not present.

_get_atoms(elements)

Retrieves a dictionary of atoms in the reactant.

Returns:: A dictionary containing atom symbols as keys and their counts as values.

_get_molecular_weight(elements)

Calculates the molecular weight of the reactant.

Returns:: The molecular weight of the reactant in grams per mole.

_get_super_string(x)

Converts numeric characters in the formula of the reactant to Unicode superscript characters.

Parameters:: x – The input string to convert.
Returns:: The input string with numeric characters replaced by super-script characters.

_get_sub_string(x)

Converts numeric characters in the formula of the reactant to Unicode subscript characters.

Parameters:: x – The input string to convert.
Returns:: The input string with numeric characters replaced by sub-script characters.

_get_reactant_string()

Creates a formatted string representing the reactant formula.

Returns:: Formatted string representation of the reactant, including subscripts for number of atoms and superscripts for charge.

PourPy.system.element_list

class PourPy.system.Constants

Bases: float, enum.Flag

Convert a string or number to a floating point number, if possible.

GAS = 8.31446262

FARADAY = 96485.3321

STANDARD_TEMPERATURE = 298.15

STANDARD_PRESSURE = 1.0

class PourPy.system.State(*args, **kwds)

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access:

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

aqueous = 'aq'

solid = 's'

gaseous = 'g'

liquid = 'l'

electron = 'e'

class PourPy.system.Defaults

Bases: object

activity = 1.0

maximum_electrode_potential = 2.0

minimum_electrode_potenital

maximum_pH_value = 16.0

minimum_pH_value = 0.0

pressure = 1.0

temperature = 298.15

reference_electrode_abbreviation = 'SHE'

reference_potential_difference = 0.0

reference_electrodes

class PourPy.system.System(filename=None)

System class that contains all required physiochemical parameters, elements and reacion constituents nessecary to create a pourbaix diagram.

set_database(database)

__str__()

Generate a string of the System object containing all chemical reactions, its temperature and pressure.

Returns:: String representation of the System.
Return type:: str

initialize()

Initialize all chemical reactions included in the system using its current physiochemical parameters.

Returns:: None
Return type:: None

write_parameters_to_file(filename)

Writes a dictionary of standard system parameters and physical constants into a JSON file.

Parameters:

filename (str) – Name of the JSON file to write parameters to.
R (float) – Ideal gas constant R = 8.31446262 J/mol/K.
F (float) – Faraday constant F = 96485.3321 A*s/mol.
T0 (float) – Standard temperature T0 = 298.15 degree Kelvin.
P0 (float) – Standard pressure P0 = 1.00 bar.
Reference_abbreviation (str) – Abbreviation of the reference electrode.
dE (float) – Potential difference of the reference electrode in volts vs. the standard hydrogen electrode.
T (float) – Temperature in degree Kelvin.
P (float) – Pressure in bar.
pHmin (float) – Minimum pH of the diagram.
pHmax (float) – Maximum pH of the diagram.
Emin (float) – Minimum potential of the diagram in volts vs. SHE.
Emax (float) – Maximum potential of the diagram in volts vs. SHE.

read_parameters_from_file(filename)

Reads system parameters from a JSON file.

Parameters:: filename (str) – Name of the JSON file to read parameters from.
Returns:: None
Return type:: None

property temperature

Get the system temperature.

Returns:: Temperature in degrees Kelvin.
Return type:: float

property pressure

Get the system pressure.

Returns:: Pressure in bar.
Return type:: float

property pHs

Get the system pH range.

Returns:: A tuple containing the minimum and maximum pH values.
Return type:: tuple

property pHmin

Get the minimum pH value of the system.

Returns:: Minimum pH value.
Return type:: float

property pHmax

Get the maximum pH value of the system.

Returns:: Maximum pH value.
Return type:: float

property electrode_potentials

Get the electrode potential range of the system and automatically check which value is the lower one an which one corresponds to the upper limit.

Returns:: A tuple containing the minimum and maximum electrode potentials.
Return type:: tuple

property Emin

Get the minimum electrode potential value of the system.

Returns:: Minimum electrode potential value in volts vs. SHE.
Return type:: float

property Emax

Get the maximum electrode potential value of the system.

Returns:: Maximum electrode potential value in volts vs. SHE.
Return type:: float

property reference_electrode

Get the reference electrode information.

Returns:: A tuple containing the reference electrode abbreviation and potential difference.
Return type:: tuple

property reference_abbreviation

Get the abbreviation of the reference electrode.

Returns:: Abbreviation of the reference electrode.
Return type:: str

property deltaE

Get the potential difference of the reference electrode in volts vs. the standard hydrogen electrode.

Returns:: Potential difference in volts.
Return type:: float

add_elements(elements: list)

Adds elements to the chemical system.

Parameters:: elements (list) – List of chemical elements in the system.

abstract add_reactions(reactions)

_(reactions: list)

Adds reactions to the chemical system.

Parameters:: reactions (list) – List of chemical reactions in the system.

_(reactions: tuple)

read_reactions_from_file(filename: str)

Reads the reactions from a file and adds reactions to the chemical system

Parameters:: filename (str) – filename with reactions

set_aqueous_activity(element: str, activity: float)

Modifies the aqueous activity of singular elements previously defined to be included in the chemical system.

Parameters:

element (str) – Chemical element in the system.
activity (float) – Chemical activity of element.

_get_elements(elements)

Validates the user-input list of chemical elements and updates the dictionary in system_parameters.json to include a dictionary of elements together with their aqueous activities.

Parameters:: elements (list) – List of chemical elements in the system.
Raises:: ValueError – Error raised if the list of elements provided contains entries that are not in element_list of know and supported elements.
Returns:: Dictionary of validated elements as keys and standard aqueous activities as values.
Return type:: dict

construct_reactions_from_reactants(reactants: dict)

Validates the user-input reactants and constructs reactions from reactants from a dictionary containing the reactants and their corresponding activities.

Parameters:: reactants (dict) – A dictionary of reactants (species) as keys and their corresponding activities as values.
Returns:: A Reaction object created based on the provided reactants and activities.
Return type:: Reaction
Raises:: ValueError – If any reactant contains elements not yet added to the system.

_get_reactions(reactions)

Validates the user-input list of chemical reactions to appear on the Pourbaix diagram.

Parameters:: reactions (list) – List of chemical reactions in the system.
Raises:: ValueError – Error raised if list entries are not in the form of a dictionary. Further error validation upon creating the reaction() object from each entry provided.
Returns:: List of chemical reaction objects featuring the systems potential and pH limits as well as the temperature and pressure.
Return type:: list

_set_aqueous_activity(element: str, activity: float) → dict

Validates the user-input element and corresponding chemical activity and updates the dictionary in system_parameters.json.

Parameters:

element (str) – Chemical element whose activity is modified.
activity (float) – Chemical activity of the element.

Raises:

ValueError – Error raised if element provided is not part of the chemical system.

Returns:

Dictionary of elements as keys and updated standard aqueous activities as values.

Return type:

dict