Reaction – Reference

Class ThermoDynamics

K_from_delta_G
delta_G_from_K
delta_G_from_enthalpy
delta_H_from_gibbs
delta_S_from_gibbs

Class Reaction

__init__
_set_kinetic_and_thermodynamic
set_macro_enzyme
READ RXN DATA:
extract_reactants
extract_reactants_formula
extract_products
extract_products_formula
extract_forward_rate
extract_reverse_rate
unpack_for_dynamics
extract_stoichiometry
extract_species_index
extract_rxn_order
extract_rxn_properties
extract_chemicals_in_reaction
DESCRIBE DATA:
describe
PRIVATE:
_standard_form_chem_eqn
_parse_reaction_term

Class ThermoDynamics

    Manage the Thermodynamics aspects

name	arguments	returns
K_from_delta_G	cls, delta_G, temp	float
Compute a reaction's equilibrium constant from the thermodynamic data :param delta_G: Change in Gibbs Free Energy (from reactants to products), in Joules :param temp: System's temperature, in degree Kelvins :return: The reaction's equilibrium constant

name

arguments

returns

K_from_delta_G

cls, delta_G, temp

float

        Compute a reaction's equilibrium constant from the thermodynamic data

        :param delta_G: Change in Gibbs Free Energy (from reactants to products), in Joules
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's equilibrium constant

name	arguments	returns
delta_G_from_K	cls, K, temp	float
Compute a reaction's change in its Gibbs Free Energy from its equilibrium constant, at the specified temperature :param K: The reaction's equilibrium constant :param temp: System's temperature, in degree Kelvins :return: The reaction's change in Gibbs Free Energy (from reactants to products), in Joules

name

arguments

returns

delta_G_from_K

cls, K, temp

float

        Compute a reaction's change in its Gibbs Free Energy from its equilibrium constant, at the specified temperature

        :param K:       The reaction's equilibrium constant
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Gibbs Free Energy (from reactants to products), in Joules

name	arguments	returns
delta_G_from_enthalpy	cls, delta_H, delta_S, temp	float
Compute the change in Gibbs Free Energy, from Enthalpy and Entropy changes :param delta_H: The reaction's change in Enthalpy (from reactants to products) :param delta_S: The reaction's change in Entropy (from reactants to products) :param temp: System's temperature, in degree Kelvins :return: The reaction's change in Free Energy (from reactants to products)

name

arguments

returns

delta_G_from_enthalpy

cls, delta_H, delta_S, temp

float

        Compute the change in Gibbs Free Energy, from Enthalpy and Entropy changes

        :param delta_H: The reaction's change in Enthalpy (from reactants to products)
        :param delta_S: The reaction's change in Entropy (from reactants to products)
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Free Energy (from reactants to products)

name	arguments	returns
delta_H_from_gibbs	cls, delta_G, delta_S, temp	float
Compute the change in Enthalpy, from changes in Gibbs Free Energy and in Entropy :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products) :param delta_S: The reaction's change in Entropy (from reactants to products) :param temp: System's temperature, in degree Kelvins :return: The reaction's change in Enthalpy (from reactants to products)

name

arguments

returns

delta_H_from_gibbs

cls, delta_G, delta_S, temp

float

        Compute the change in Enthalpy, from changes in Gibbs Free Energy and in Entropy

        :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products)
        :param delta_S: The reaction's change in Entropy (from reactants to products)
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Enthalpy (from reactants to products)

name	arguments	returns
delta_S_from_gibbs	cls, delta_G, delta_H, temp	float
Compute the change in Entropy, from changes in the Gibbs Free Energy and in Enthalpy :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products) :param delta_H: The reaction's change in Enthalpy (from reactants to products) :param temp: System's temperature, in degree Kelvins :return: The reaction's change in Entropy (from reactants to products)

name

arguments

returns

delta_S_from_gibbs

cls, delta_G, delta_H, temp

float

        Compute the change in Entropy, from  changes in the Gibbs Free Energy and in Enthalpy

        :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products)
        :param delta_H: The reaction's change in Enthalpy (from reactants to products)
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Entropy (from reactants to products)

Class Reaction

    Data about a SINGLE reaction,
    including:
        - stoichiometry
        - kinetic data (reaction rates, reaction orders)
        - thermodynamic data (temperature, changes in enthalpy/entropy/Gibbs Free Energy)
        - list of involved enzymes


    (Note: this data will eventually be stored in a Neo4j graph database)

    Each reaction contains:
            "reactants"
            "products"
            "kF"    (forward reaction rate constant)
            "kR"    (reverse reaction rate constant)
            "K"     (equilibrium constant - from either kinetic or thermodynamic data; if both present, they must match up!)
            "Delta_H" (change in Enthalpy: Enthalpy of Products - Enthalpy of Reactants)
            "Delta_S" (change in Entropy)
            "Delta_G" (change in Gibbs Free Energy)
                        Note - at constant temperature T :  Delta_G = Delta_H - T * Delta_S
                        Equilibrium constant = exp(-Delta_G / RT)
            "enzyme" (the index of a chemical that catalyzes this reaction)
            "macro_enzyme" (The pair (macromolecule name, binding site number))

        Each Reactant and each Product is a triplet of the form: (stoichiometry, species index, reaction order).
        The "reaction order" in that triplet refers to the forward reaction for reactants, and the reverse reaction for products.
        Note that reactants and products might be catalysts

name	arguments	returns
__init__	self, chem_data, reactants: Union[int, str, list], products: Union[int, str, list], forward_rate=None, reverse_rate=None, delta_H=None, delta_S=None, delta_G=None
Add the parameters of a SINGLE reaction, optionally including kinetic and/or thermodynamic data. The involved chemicals must be already registered - use add_chemical() if needed. NOTE: in the reactants and products, if the stoichiometry and/or reaction order aren't specified, they're assumed to be 1. Their full structure is the triplet (stoichiometry coefficient, name, reaction order) EXAMPLES of formats for each item of the reactants and products (assuming that the chemical species with index 5 is called "F"): "F" gets turned into: (1, 5, 1) (3, "F") (3, 5, 1) (3, "F", 2) (3, 5, 2) It's equally acceptable to use LISTS in lieu of tuples :param chem_data: Object of type "ReactionData" :param reactants: A list of triplets (stoichiometry, species name, reaction order), or simplified terms in various formats; for details, see above. If not a list, it will get turned into one :param products: A list of triplets (stoichiometry, species name, reaction order of REVERSE reaction), or simplified terms in various formats; for details, see above. If not a list, it will get turned into one :param forward_rate: [OPTIONAL] Forward reaction rate constant :param reverse_rate: [OPTIONAL] Reverse reaction rate constant :param delta_H: [OPTIONAL] Change in Enthalpy (from reactants to products) :param delta_S: [OPTIONAL] Change in Entropy (from reactants to products) :param delta_G: [OPTIONAL] Change in Free Energy (from reactants to products)

name

arguments

returns

__init__

self, chem_data, reactants: Union[int, str, list], products: Union[int, str, list], forward_rate=None, reverse_rate=None, delta_H=None, delta_S=None, delta_G=None

        Add the parameters of a SINGLE reaction, optionally including kinetic and/or thermodynamic data.
        The involved chemicals must be already registered - use add_chemical() if needed.

        NOTE: in the reactants and products, if the stoichiometry and/or reaction order aren't specified,
              they're assumed to be 1.
              Their full structure is the triplet (stoichiometry coefficient, name, reaction order)

        EXAMPLES of formats for each item of the reactants and products
        (*assuming* that the chemical species with index 5 is called "F"):
                    "F"         gets turned into:   (1, 5, 1)
                    (3, "F")                        (3, 5, 1)
                    (3, "F", 2)                     (3, 5, 2)
                    It's equally acceptable to use LISTS in lieu of tuples

        :param chem_data:       Object of type "ReactionData"
        :param reactants:       A list of triplets (stoichiometry, species name, reaction order),
                                    or simplified terms in various formats; for details, see above.
                                    If not a list, it will get turned into one
        :param products:        A list of triplets (stoichiometry, species name, reaction order of REVERSE reaction),
                                    or simplified terms in various formats; for details, see above.
                                    If not a list, it will get turned into one
        :param forward_rate:    [OPTIONAL] Forward reaction rate constant
        :param reverse_rate:    [OPTIONAL] Reverse reaction rate constant
        :param delta_H:         [OPTIONAL] Change in Enthalpy (from reactants to products)
        :param delta_S:         [OPTIONAL] Change in Entropy (from reactants to products)
        :param delta_G:         [OPTIONAL] Change in Free Energy (from reactants to products)

name	arguments	returns
_set_kinetic_and_thermodynamic	self, forward_rate, reverse_rate, delta_H, delta_S, delta_G, temp	None
Set all the kinetic and thermodynamic data derivable - directly or indirectly - from the passed arguments, storing it in object attributes. Raise an Exception if any inconsistency is detected. :return: None

name

arguments

returns

_set_kinetic_and_thermodynamic

self, forward_rate, reverse_rate, delta_H, delta_S, delta_G, temp

None

        Set all the kinetic and thermodynamic data derivable - directly or indirectly - from the passed arguments,
        storing it in object attributes.
        Raise an Exception if any inconsistency is detected.

        :return:    None

name	arguments	returns
set_macro_enzyme	self, macromolecule: str, site_number: int	None
Register that the given macromolecule catalyzes this reaction at the given site :param macromolecule: Name of macromolecule acting as a catalyst :param site_number: Integer to identify a binding site on the above macromolecule :return: None

name

arguments

returns

set_macro_enzyme

self, macromolecule: str, site_number: int

None

        Register that the given macromolecule catalyzes this reaction at the given site

        :param macromolecule:   Name of macromolecule acting as a catalyst
        :param site_number:     Integer to identify a binding site on the above macromolecule
        :return:                None

READ RXN DATA

name	arguments	returns
extract_reactants	self	[(int, int, int)]
Return a list of triplets with details of the reactants of the given reaction :return: A list of triplets of the form (stoichiometry, species index, reaction order)

name	arguments	returns
extract_reactants_formula	self	str
Return a string with a user-friendly form of the left (reactants) side of the reaction formula EXAMPLE: "CH4 + 2 O2" :return:

name	arguments	returns
extract_products	self	[(int, int, int)]
Return a list of triplet with details of the products of the given reaction :return: A list of triplets of the form (stoichiometry, species index, reaction order)

name	arguments	returns
extract_products_formula	self	str
Return a string with a user-friendly form of the right (products) side of the reaction formula :return:

name	arguments	returns
extract_forward_rate	self	float
:return: The value of the forward rate constant for the above reaction

name	arguments	returns
extract_reverse_rate	self	float
:return: The value of the reverse (back) rate constant for the above reaction

name	arguments	returns
unpack_for_dynamics	self	tuple
A convenient unpacking meant for dynamics simulations that need the reactants, the products, and the forward and reverse rate constants :return: A 4-element tuple

name	arguments	returns
extract_stoichiometry	self, term: (int, int, int)	int
Return the stoichiometry coefficient, from a reaction term :param term: :return:

name	arguments	returns
extract_species_index	self, term: (int, int, int)	int
Return the index of the chemical species, from a reaction term :param term: :return:

name	arguments	returns
extract_rxn_order	self, term: (int, int, int)	int
Return the reaction order, from a reaction term :param term: :return:

name	arguments	returns
extract_rxn_properties	self	{}
Create a dictionary with the numerical properties of the given reaction (skipping any lists or None values) For example, reaction rates, Delta G, equilibrium constant :return: EXAMPLE: {'kF': 3.0, 'kR': 2.0, 'Delta_G': -1005.1305052750387, 'K': 1.5}

name

arguments

returns

extract_rxn_properties

self

{}

        Create a dictionary with the numerical properties of the given reaction
        (skipping any lists or None values)
        For example, reaction rates, Delta G, equilibrium constant

        :return:    EXAMPLE: {'kF': 3.0, 'kR': 2.0, 'Delta_G': -1005.1305052750387, 'K': 1.5}

name	arguments	returns
extract_chemicals_in_reaction	self, exclude_enzyme=False	{int}
Return a SET of indices (being a set, it's NOT in any particular order) of all the chemicals in this reaction :param exclude_enzyme: If True, any enzyme, if present, won't be included TODO - test :return: A SET of indices of the chemicals involved in this reaction Note: being a set, it's NOT in any particular order

name

arguments

returns

extract_chemicals_in_reaction

self, exclude_enzyme=False

{int}

        Return a SET of indices (being a set, it's NOT in any particular order)
        of all the chemicals in this reaction

        :param exclude_enzyme:  If True, any enzyme, if present, won't be included  TODO - test
        :return:                A SET of indices of the chemicals involved in this reaction
                                Note: being a set, it's NOT in any particular order

DESCRIBE DATA

name	arguments	returns
describe	self, concise=False	str
Return as a string, a user-friendly plain-text form of the reaction EXAMPLE (concise): "CH4 + 2 O2 <-> CO2 + 2 H2O" EXAMPLE (not concise): "CH4 + 2 O2 <-> CO2 + 2 H2O (kF = 3.0 / kR = 2.0 / Delta_G = -1,005.13 / K = 1.5) \| 1st order in all reactants & products" :param concise: If True, less detail is shown :return: A string with a description of the specified reaction

name

arguments

returns

describe

self, concise=False

str

        Return as a string, a user-friendly plain-text form of the reaction
        EXAMPLE (concise):      "CH4 + 2 O2 <-> CO2 + 2 H2O"
        EXAMPLE (not concise):  "CH4 + 2 O2 <-> CO2 + 2 H2O  (kF = 3.0 / kR = 2.0 / Delta_G = -1,005.13 / K = 1.5) | 1st order in all reactants & products"

        :param concise:     If True, less detail is shown
        :return:            A string with a description of the specified reaction

PRIVATE

name	arguments	returns
_standard_form_chem_eqn	self, eqn_side: list	str
Return a user-friendly form of a side of a chemical equation. EXAMPLE: turn [(1, 0, 1), (2, 8, 1)] into "Fe + 2 Cl" (if species 0 is named "Fe" and species 8 is "Cl") Note: the reaction order is NOT used :param eqn_side: A list encoding either side of a chemical equation :return: A string with a user-friendly form of a side of a chemical equation

name

arguments

returns

_standard_form_chem_eqn

self, eqn_side: list

str

        Return a user-friendly form of a side of a chemical equation.

        EXAMPLE:  turn [(1, 0, 1), (2, 8, 1)]  into  "Fe + 2 Cl"  (if species 0 is named "Fe" and species 8 is "Cl")

        Note: the reaction order is NOT used

        :param eqn_side:    A list encoding either side of a chemical equation
        :return:            A string with a user-friendly form of a side of a chemical equation

name	arguments	returns
_parse_reaction_term	self, term: Union[int, str, tuple, list], name="term"	(int, int, int)
Accept various ways to specify a reaction term, and return a standardized tuple form of it. In the tuples or lists: - optional 1st entry is the stoichiometry - required entry is the chemical name - optional 3rd one is the reaction order EXAMPLES (assuming that the chemical species with index 5 is called "F"): "F" gets turned into: (1, 5, 1) (3, "F") (3, 5, 1) (3, "F", 2) (3, 5, 2) It's equally acceptable to use LISTS in lieu of tuples :param term: A string (a chemical name) OR a pair (stoichiometry coeff, name) OR a triplet (stoichiometry coeff, name, reaction order) :param name: An optional nickname to refer to this term in error messages, if applicable (for example, "reactant" or "product") :return: A standardized tuple form, of the form (stoichiometry, species index, reaction_order), where all terms are integers

name

arguments

returns

_parse_reaction_term

self, term: Union[int, str, tuple, list], name="term"

(int, int, int)

        Accept various ways to specify a reaction term, and return a standardized tuple form of it.
        In the tuples or lists:
            - optional 1st entry is the stoichiometry
            - required entry is the chemical name
            - optional 3rd one is the reaction order

        EXAMPLES (*assuming* that the chemical species with index 5 is called "F"):
            "F"          gets turned into:  (1, 5, 1)
            (3, "F")                        (3, 5, 1)
            (3, "F", 2)                     (3, 5, 2)
            It's equally acceptable to use LISTS in lieu of tuples

        :param term:    A string (a chemical name)
                            OR  a pair (stoichiometry coeff, name)
                            OR  a triplet (stoichiometry coeff, name, reaction order)
        :param name:    An optional nickname to refer to this term in error messages, if applicable
                            (for example, "reactant" or "product")
        :return:        A standardized tuple form, of the form (stoichiometry, species index, reaction_order),
                            where all terms are integers