Reaction – Reference

Source code

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)
            "enzyme" (the index of a chemical that catalyzes this reaction)
            "macro_enzyme" (The pair (macromolecule name, binding site number))
            plus thermodynamic data: delta_H, delta_S, delta_G, K (equilibrium constant) -
                                     for details see class "ThermoDynamics"

    Internally, 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 to the reverse reaction for products.
    Note that any reactant and products might be catalysts
    
nameargumentsreturns
__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
        Create the structure for a new SINGLE chemical reaction,
        optionally including its kinetic and/or thermodynamic data.
        All the involved chemicals must be already registered - use add_chemical() if needed.

        NOTE: in the reactants and products, if the stoichiometry coefficients aren't specified,
              they're assumed to be 1.
              The reaction orders, if not specified, are assumed to be equal to their corresponding
              stoichiometry coefficients.

              The full structure of each term in the list of reactants and of products
              is the triplet:  (stoichiometry coefficient, name, reaction order)

              EXAMPLES of formats to use for each term in the lists of the reactants and of the products:
                "F"         is taken to mean (1, "F", 1) - default stoichiometry and reaction order
                (2, "F")    is taken to mean (2, "F", 2) - stoichiometry coefficient used as default for reaction order
                (2, "F", 1) means stoichiometry coefficient 2 and reaction order 1 - no defaults invoked
              It's equally acceptable to use LISTS in lieu of tuples for the pair or triplets

        :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)
        
nameargumentsreturns
set_macro_enzymeself, macromolecule: str, site_number: intNone
        Register that the given macromolecule, at the given site on it,
        catalyzes this reaction

        :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

nameargumentsreturns
extract_reactantsself[(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)
        
nameargumentsreturns
extract_reactants_formulaselfstr
        Return a string with a user-friendly form of the left (reactants) side of the reaction formula
        EXAMPLE: "CH4 + 2 O2"

        :return:    A string with one side of a chemical reaction
        
nameargumentsreturns
extract_productsself[(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)
        
nameargumentsreturns
extract_products_formulaselfstr
        Return a string with a user-friendly form of the right (products) side of the reaction formula

        :return:    A string with one side of a chemical reaction
        
nameargumentsreturns
extract_forward_rateselffloat

        :return:    The value of the forward rate constant for this reaction
        
nameargumentsreturns
extract_reverse_rateselffloat

        :return:    The value of the reverse (back) rate constant for this reaction
        
nameargumentsreturns
extract_equilibrium_constantselffloat

        :return:    The value of the equilibrium constant for this reaction
        
nameargumentsreturns
unpack_for_dynamicsselftuple
        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, containing:
                        (reactants , products , forward rate constant , reverse rate constant)
                        Note: both reactants products are lists of triplets
        
nameargumentsreturns
extract_stoichiometryself, term :(int, int, int)int
        Return the stoichiometry coefficient, from a reaction term

        :param term:    A triplet of integers representing a reaction term
        :return:        An integer with the stoichiometry coefficient
        
nameargumentsreturns
extract_species_indexself, term :(int, int, int)int
        Return the index of the chemical species, from a reaction term

        :param term:    A triplet of integers representing a reaction term
        :return:        An integer with the index of the chemical species in the term
        
nameargumentsreturns
extract_rxn_orderself, term :(int, int, int)int
        Return the reaction order, from a reaction term

        :param term:    A triplet of integers representing a reaction term
        :return:        An integer with the reaction order for this term
        
nameargumentsreturns
extract_rxn_propertiesself{}
        Create a dictionary with the numerical properties of the given reaction
        (skipping any lists or None values)
        Possible values include:
            forward and reverse reaction rates, ΔH, ΔS, ΔG, K (equilibrium constant)

        :return:    EXAMPLE: {'kF': 3.0, 'kR': 2.0, 'delta_G': -1005.1305052750387, 'K': 1.5}
        
nameargumentsreturns
extract_chemicals_in_reactionself, exclude_enzyme=FalseSet[int]
        Return a SET of indices (being a set, it's NOT in any particular order)
        identifying all the chemicals appearing in this reaction.
        Optionally, exclude any that participate in a catalytic role
        (appearing identically on both sides of the reaction)

        :param exclude_enzyme:  If True, any enzyme, if present, won't be included
        :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

nameargumentsreturns
describeself, concise=Falsestr
        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
        

ANALYSIS

nameargumentsreturns
reaction_quotientself, conc, explain=FalseUnion[np.double, Tuple[np.double, str]]
        Compute the "Reaction Quotient" (aka "Mass–action Ratio"),
        given the concentrations of chemicals involved in this reaction

        :param conc:        Dictionary with the concentrations of the species involved in the reaction.
                            The keys are the chemical names
                                EXAMPLE: {'A': 23.9, 'B': 36.1}
        :param explain:     If True, it also returns the math formula being used for the computation
                                EXAMPLES:   "([C][D]) / ([A][B])"
                                            "[B] / [A]^2"

        :return:            If explain is False, return value for the "Reaction Quotient" (aka "Mass–action Ratio");
                                if True, return a pair with that quotient and a string with the math formula that was used.
                                Note that the reaction quotient is a Numpy scalar that might be np.inf or np.nan
        

PRIVATE

nameargumentsreturns
_standard_form_chem_eqnself, eqn_side: liststr
        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
        
nameargumentsreturns
_parse_reaction_termself, term: Union[str, tuple, list], name="term"(int, int, int)
        Accept various ways to specify a reaction term, and return a standardized triplet form for it.

        NOTE:   A) if the stoichiometry coefficient isn't specified, it defaults to 1
                B) if the reaction order isn't specified, it defaults to the stoichiometry coefficient

        In the passed tuples or lists:
            - required 1st entry is the stoichiometry
            - required 2nd entry is the chemical name
            - optional 3rd one is the reaction order.  If unspecified, it defaults to the stoichiometry

        If just a string is being passed, it is taken to be the chemical name,
        with stoichiometry and reaction order both 1

        EXAMPLES (*assuming* that the chemical species with index 5 is called "F"):
            "F"          gets turned into:  (1, 5, 1)   - defaults used for stoichiometry and reaction order
            (2, "F")                        (2, 5, 2)   - default used for reaction order
            (2, "F", 1)                     (2, 5, 1)   - no defaults invoked
            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, handy to refer to this term in error messages if needed
                            (for example, "reactant" or "product")
        :return:        A standardized triplet of the form (stoichiometry, species index, reaction_order),
                            where all terms are integers
        
nameargumentsreturns
_set_kinetic_and_thermodynamicself, forward_rate, reverse_rate, delta_H, delta_S, delta_G, tempNone
        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