Various Subtypes of Reactions – Reference Guide

This guide is for versions 1.0.0rc.7+ (Release Candidate)

7 classes: ReactionCommon, ReactionElementary, ReactionUnimolecular, ReactionSynthesis, ReactionDecomposition, ReactionEnzyme, ReactionGeneric

The objects from those classes are managed by the class ReactionRegistry.

Source code

Class ReactionCommon

    Foundational base class for ALL individual reactions.

    Typically NOT instantiated by the user.

    Individual reactions classes need to provide the following methods:

        extract_stoichiometry()
        extract_chem_label()

        reaction_details()
        extract_intermediate()
        extract_rxn_properties()
        set_thermodynamic_data()
        extract_forward_rate()
        extract_reverse_rate()
        extract_equilibrium_constant()

        describe()

        extract_reactant_labels()
        extract_reactants()

        extract_product_labels()
        extract_products()

        extract_chemicals_in_reaction()

        extract_rxn_properties()     A dict

        step_simulation()

name	arguments	returns
__init__	active=True, temp=None
:param active: [NOT YET IMPLEMENTED] If False, the reaction is regarded as inactive :param temp: In Kelvins

name	arguments	returns
reaction_details	rxn_properties :dict	str
Return a string with some details about the parameters of this reaction :param rxn_properties: A dictionary with numerical properties of interest for the reaction EXAMPLE: {'kF': 3.0, 'kR': 2.0, 'delta_G': -1005.13, 'K': 1.5} :return: A string with some details about the parameters of this reaction EXAMPLE: " (kF = 3 / kR = 2 / Delta_G = -1,005.13 / Temp = 25 C)"

name

arguments

returns

reaction_details

rxn_properties :dict

str

        Return a string with some details about the parameters of this reaction

        :param rxn_properties:  A dictionary with numerical properties of interest for the reaction
                                    EXAMPLE: {'kF': 3.0, 'kR': 2.0, 'delta_G': -1005.13, 'K': 1.5}

        :return:                A string with some details about the parameters of this reaction
                                    EXAMPLE: "  (kF = 3 / kR = 2 / Delta_G = -1,005.13 / Temp = 25 C)"

name	arguments	returns
extract_stoichiometry	term :(int, str)	int
Return the stoichiometry coefficient, from a reaction "TERM" :param term: A pair (int, str) representing a reaction term :return: An integer with the stoichiometry coefficient

name	arguments	returns
extract_chem_label	term :(int, str)	str
Return the label of the chemical species, from a reaction "TERM" :param term: A pair (int, str) representing a reaction term :return: The name of the chemical species in the term

Class ReactionElementary

    Base class for all reactions that can be modeled kinetically as happening in 1 step
    (i.e. with no intermediaries).

    Typically NOT instantiated by the user.

name	arguments	returns
__init__	reversible=True, kF=None, kR=None, delta_H=None, delta_S=None, delta_G=None, **kwargs
:param reversible: :param kF: :param kR: :param delta_H: :param delta_S: :param delta_G: :param kwargs:

name	arguments	returns
equilibrium_constant_from_kinetic_data	K=None, kF=None, kR=None	None
True for Elementary reactions (and, more generally, for any reaction that follows mass-action kinetics) :param K: The reaction's equilibrium constant :param kF: The forward reaction's reaction rate constant :param kR: The reverse reaction's reaction rate constant :return: None

name

arguments

returns

equilibrium_constant_from_kinetic_data

K=None, kF=None, kR=None

None

        True for Elementary reactions
        (and, more generally, for any reaction that follows mass-action kinetics)

        :param K:   The reaction's equilibrium constant
        :param kF:  The forward reaction's reaction rate constant
        :param kR:  The reverse reaction's reaction rate constant
        :return:    None

name	arguments	returns
set_rate_constants_from_equilibrium_constant	K	None
Set, as needed, a missing reaction rate constant (kF or kR) from the other one and the given equilibrium constant K. If all values already exist, and an inconsistency is detected, an Exception will be raised. Note: the reaction's equilibrium constant and its kinetic rate constants are in the relationship K = kF / kR for any (and, more generally, for any reaction that follows mass-action kinetics) :param K: The reaction's equilibrium constant :return: None

name

arguments

returns

set_rate_constants_from_equilibrium_constant

None

        Set, as needed, a missing reaction rate constant (kF or kR)
        from the other one and the given equilibrium constant K.
        If all values already exist, and an inconsistency is detected, an Exception will be raised.

        Note: the reaction's equilibrium constant and its kinetic rate constants are
              in the relationship K = kF / kR for any
              (and, more generally, for any reaction that follows mass-action kinetics)

        :param K:   The reaction's equilibrium constant
        :return:    None

name

arguments

returns

extract_rxn_properties

{}

        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}

name	arguments	returns
set_thermodynamic_data	temp :float	None
Set all the thermodynamic data derivable from the given temperature, and all previously passed kinetic and thermodynamic data. Raise an Exception if any inconsistency is detected. :param temp: System temperature in Kelvins. For now, assumed constant everywhere, and unvarying (or very slowly varying). If the temp gradually changes, periodically call this method. :return: None

name

arguments

returns

set_thermodynamic_data

temp :float

None

        Set all the thermodynamic data derivable from the given temperature,
        and all previously passed kinetic and thermodynamic data.
        Raise an Exception if any inconsistency is detected.

        :param temp:    System temperature in Kelvins.  For now, assumed constant everywhere,
                            and unvarying (or very slowly varying).
                            If the temp gradually changes, periodically call this method.
        :return:        None

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

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

name	arguments	returns
extract_equilibrium_constant		float
:return: The value of the equilibrium constant for this reaction

name	arguments	returns
extract_intermediate		str \| None
Return the name of the reaction intermediate species, or None if there's no intermediate :return:

Class ReactionUnimolecular

    Elementary reaction of type A <-> P, of first order in `A` and `P`

name	arguments	returns
__init__	reactant :str, product :str, **kwargs
:param reactant: Label of the reaction's single reactant :param product: Label of the reaction's single product (cannot be the same as the reactant) :param kwargs: Other named arguments to pass thru to the parent class

name

arguments

returns

__init__

reactant :str, product :str, **kwargs

        :param reactant:    Label of the reaction's single reactant
        :param product:     Label of the reaction's single product (cannot be the same as the reactant)
        :param kwargs:      Other named arguments to pass thru to the parent class

name	arguments	returns
describe	concise=False	str
Return as a string, a user-friendly plain-text form of the reaction :param concise: If True, less detail is shown :return: A string with a description of this reaction

name	arguments	returns
extract_reactant_labels		[str]
Return the list of ALL the reactant labels in this reaction :return: A list of ALL the reactant labels in this reaction

name	arguments	returns
extract_reactants		[(int, str)]
Return a list of pairs with details of the reactants of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_reactants_formula		str
Return a string with a user-friendly form of the left (reactants) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_product_labels		[str]
Return the list of the labels ALL the products of this reaction :return:

name	arguments	returns
extract_products		[(int, str)]
Return a list of pairs with details of the products of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_products_formula		str
Return a string with a user-friendly form of the right (product) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_chemicals_in_reaction		Set[str]
Return a SET of the labels of ALL the chemicals appearing in this reaction :return: A SET of the labels of the chemicals involved in this reaction Note: being a set, it's NOT in any particular order

name	arguments	returns
reaction_quotient	conc, explain=False	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 labels 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

name

arguments

returns

reaction_quotient

conc, explain=False

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 labels
                                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

name	arguments	returns
determine_reaction_rate	conc_dict :dict	float
For the specified concentrations of the chemicals in the unimolecular reaction, determine its current reaction's "rate" (aka "velocity"), i.e. its "forward rate" minus its "reverse rate". :param conc_dict: A dict mapping chemical labels to their concentrations, for all the chemicals involved in this reaction EXAMPLE: {"B": 1.5, "F": 31.6, "D": 19.9} :return: The differences between the reaction's forward and reverse rates

name

arguments

returns

determine_reaction_rate

conc_dict :dict

float

        For the specified concentrations of the chemicals in the unimolecular reaction,
        determine its current reaction's "rate" (aka "velocity"),
        i.e. its "forward rate" minus its "reverse rate".

        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6, "D": 19.9}
        :return:            The differences between the reaction's forward and reverse rates

name	arguments	returns
step_simulation	delta_time, conc_dict :dict, exact=False	(dict, float)
Simulate the unimolecular reaction R <-> P, over the specified time interval, using either the exact analytical solution, or the "Forward Euler" approximation method :param delta_time: The time duration of this individual reaction step - assumed to be small enough that the concentrations won't vary significantly during this span :param conc_dict: A dict mapping chemical labels to their concentrations, for all the chemicals involved in this reaction EXAMPLE: {"R": 1.5, "P": 31.6} :param exact: [OPTIONAL] If True, use the exact analytical solution; if False (default), use the "Forward Euler" approximation method :return: The pair (increment_dict_single_rxn, rxn_rate) - increment_dict_single_rxn is the mapping of chemical label to their concentration CHANGES during this step EXAMPLE: {"R": -0.2, "P": 0.2} (meaning [R] decreases by 0.2 and [P] increases by the same amount) - rxn_rate is the reaction rate ("velocity") for this reaction (rate of change of the product), at the START of the simulation step EXAMPLE: 3.5

name

arguments

returns

step_simulation

delta_time, conc_dict :dict, exact=False

(dict, float)

        Simulate the unimolecular reaction R <-> P, over the specified time interval,
        using either the exact analytical solution, or the "Forward Euler" approximation method

        :param delta_time:  The time duration of this individual reaction step - assumed to be small enough that the
                                concentrations won't vary significantly during this span
        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"R": 1.5, "P": 31.6}
        :param exact:       [OPTIONAL] If True, use the exact analytical solution;
                                if False (default), use the "Forward Euler" approximation method

        :return:            The pair (increment_dict_single_rxn, rxn_rate)
                                - increment_dict_single_rxn is the mapping of chemical label to their concentration CHANGES
                                                            during this step
                                                            EXAMPLE: {"R": -0.2, "P": 0.2}
                                                                     (meaning [R] decreases by 0.2 and [P] increases by the same amount)

                                - rxn_rate                  is the reaction rate ("velocity") for this reaction
                                                            (rate of change of the product), at the START of the simulation step
                                                            EXAMPLE: 3.5

name	arguments	returns
find_equilibrium_conc	conc_dict :dict	dict
Determine the equilibrium concentrations that would be eventually reached by the chemicals of this reaction, given the specified concentrations, IN THE ABSENCE of any other reaction. :param conc_dict: A dict mapping chemical labels to their initial concentrations, for all the chemicals involved in this reaction EXAMPLE: {"B": 1.5, "F": 31.6} :return: A dict mapping the above chemical labels to their equilibrium concentrations

name

arguments

returns

find_equilibrium_conc

conc_dict :dict

dict

        Determine the equilibrium concentrations that would be eventually reached
        by the chemicals of this reaction,
        given the specified concentrations,
        IN THE ABSENCE of any other reaction.

        :param conc_dict:   A dict mapping chemical labels to their initial concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6}

        :return:            A dict mapping the above chemical labels to their equilibrium concentrations

Class ReactionSynthesis

    Bimolecular reactions of type A + B <-> P,
    of first order for each participating chemical.

name	arguments	returns
__init__	reactants :(str, str), product :str, **kwargs
:param reactants: Pair with the labels of the 2 reactants (possibly the same) :param product: Label of the reaction's single product (cannot be the same as any of the reactants) :param kwargs: Other named arguments to pass thru to the parent class

name

arguments

returns

__init__

reactants :(str, str), product :str, **kwargs

        :param reactants:   Pair with the labels of the 2 reactants (possibly the same)
        :param product:     Label of the reaction's single product (cannot be the same as any of the reactants)
        :param kwargs:      Other named arguments to pass thru to the parent class

name

arguments

returns

describe

concise=False

str

        Return as a string, a user-friendly plain-text form of the reaction

        :param concise:     If True, less detail is shown
        :return:            A string with a description of this reaction
                            EXAMPLES of concise version:
                                A + B <-> P
                                2 C <-> P

name	arguments	returns
extract_reactant_labels		[str]
Return the list of ALL the reactant labels in this reaction :return: The list of ALL the reactant labels in this reaction

name	arguments	returns
extract_reactants		[(int, str)]
Return a list of pairs with details of the reactants of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_reactants_formula		str
Return a string with a user-friendly form of the left (reactants) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_product_labels		[str]
Return the list of the labels ALL the products of this reaction :return:

name	arguments	returns
extract_products		[(int, str)]
Return a list of pairs with details of the products of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_products_formula		str
Return a string with a user-friendly form of the right (product) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_chemicals_in_reaction		Set[str]
Return a SET of the labels of ALL the chemicals appearing in this reaction :return: A SET of the labels of the chemicals involved in this reaction Note: being a set, it's NOT in any particular order

name	arguments	returns
reaction_quotient	conc, explain=False	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 labels 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

name

arguments

returns

reaction_quotient

conc, explain=False

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 labels
                                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

name	arguments	returns
determine_reaction_rate	conc_dict :dict	float
For the specified concentrations of the chemicals in the synthesis reaction, determine its initial reaction's "rate" (aka "velocity"), i.e. its "forward rate" minus its "reverse rate", at the start of the time step. :param conc_dict: A dict mapping chemical labels to their concentrations, for all the chemicals involved in this reaction EXAMPLE: {"B": 1.5, "F": 31.6, "D": 19.9} :return: The differences between the reaction's forward and reverse rates

name

arguments

returns

determine_reaction_rate

conc_dict :dict

float

        For the specified concentrations of the chemicals in the synthesis reaction,
        determine its initial reaction's "rate" (aka "velocity"),
        i.e. its "forward rate" minus its "reverse rate",
        at the start of the time step.

        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6, "D": 19.9}
        :return:            The differences between the reaction's forward and reverse rates

name	arguments	returns
step_simulation	delta_time, conc_dict :dict, exact=False	(dict, float)
Simulate the synthesis reaction A + B <-> C, over the specified time interval, using the "Forward Euler" method :param delta_time: The time duration of this individual reaction step - assumed to be small enough that the concentrations won't vary significantly during this span :param conc_dict: A dict mapping chemical labels to their concentrations, for all the chemicals involved in this reaction EXAMPLE: {"A": 1.5, "B": 31.6, "C": 19.9} :param exact: [OPTIONAL] If True, use the exact analytical solution; if False (default), use the "Forward Euler" approximation method :return: The pair (increment_dict_single_rxn, rxn_rate) - increment_dict_single_rxn is the mapping of chemical labels to their concentration CHANGES during this step - rxn_rate is the reaction rate ("velocity") for this reaction (rate of change of the product) EXAMPLE of increment_dict_single_rxn: "A": -1.3, "B": 2.9, "C": -1.6

name

arguments

returns

step_simulation

delta_time, conc_dict :dict, exact=False

(dict, float)

        Simulate the synthesis reaction A + B <-> C, over the specified time interval,
        using the "Forward Euler" method

        :param delta_time:  The time duration of this individual reaction step - assumed to be small enough that the
                                concentrations won't vary significantly during this span
        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"A": 1.5, "B": 31.6, "C": 19.9}
        :param exact:       [OPTIONAL] If True, use the exact analytical solution;
                                if False (default), use the "Forward Euler" approximation method

        :return:            The pair (increment_dict_single_rxn, rxn_rate)
                                - increment_dict_single_rxn is the mapping of chemical labels to their concentration CHANGES
                                                            during this step
                                - rxn_rate                  is the reaction rate ("velocity") for this reaction
                                                            (rate of change of the product)
                                EXAMPLE of increment_dict_single_rxn: "A": -1.3, "B": 2.9, "C": -1.6

name	arguments	returns
find_equilibrium_conc	conc_dict :dict	dict
Determine the equilibrium concentrations that would be eventually reached by the chemicals of this reaction, given the specified concentrations, IN THE ABSENCE of any other reaction. :param conc_dict: A dict mapping chemical labels to their initial concentrations, for all the chemicals involved in this reaction EXAMPLE: {"B": 1.5, "F": 31.6} :return: A dict mapping the above chemical labels to their equilibrium concentrations

name

arguments

returns

find_equilibrium_conc

conc_dict :dict

dict

        Determine the equilibrium concentrations that would be eventually reached
        by the chemicals of this reaction,
        given the specified concentrations,
        IN THE ABSENCE of any other reaction.

        :param conc_dict:   A dict mapping chemical labels to their initial concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6}

        :return:            A dict mapping the above chemical labels to their equilibrium concentrations

Class ReactionDecomposition

    Bimolecular reactions of type A <-> B + C
    of first order for each participating chemical.

name	arguments	returns
__init__	reactant :str, products :(str, str), **kwargs
:param reactant: Label of the reaction's single reactant (cannot be the same as any of the products) :param products: Pair with the labels of the 2 reaction products (possibly the same) :param kwargs: Other named arguments to pass thru to the parent class

name

arguments

returns

__init__

reactant :str, products :(str, str), **kwargs

        :param reactant:    Label of the reaction's single reactant (cannot be the same as any of the products)
        :param products:    Pair with the labels of the 2 reaction products (possibly the same)
        :param kwargs:      Other named arguments to pass thru to the parent class

name

arguments

returns

describe

concise=False

str

        Return as a string, a user-friendly plain-text form of the reaction

        :param concise:     If True, less detail is shown
        :return:            A string with a description of this reaction
                            EXAMPLES of concise version:
                                A <-> P + Q
                                D <-> 2 P

name	arguments	returns
extract_reactant_labels		[str]
Return the list of ALL the reactant labels in this reaction :return:

name	arguments	returns
extract_reactants		[(int, str)]
Return a list of pairs with details of the reactants of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_reactants_formula		str
Return a string with a user-friendly form of the left (reactants) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_product_labels		[str]
Return the list of the labels ALL the products of this reaction :return:

name	arguments	returns
extract_products		[(int, str)]
Return a list of pairs with details of the products of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_products_formula		str
Return a string with a user-friendly form of the right (product) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_chemicals_in_reaction		Set[str]
Return a SET of the labels of ALL the chemicals appearing in this reaction :return: A SET of the labels of the chemicals involved in this reaction Note: being a set, it's NOT in any particular order

name	arguments	returns
reaction_quotient	conc, explain=False	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 labels 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

name

arguments

returns

reaction_quotient

conc, explain=False

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 labels
                                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

name	arguments	returns
determine_reaction_rate	conc_dict :dict	float
For the specified concentrations of the chemicals in the decomposition reaction, determine its initial reaction's "rate" (aka "velocity"), i.e. its "forward rate" minus its "reverse rate", at the start of the time step. :param conc_dict: A dict mapping chemical labels to their concentrations, for all the chemicals involved in this reaction EXAMPLE: {"B": 1.5, "F": 31.6, "D": 19.9} :return: The differences between the reaction's forward and reverse rates

name

arguments

returns

determine_reaction_rate

conc_dict :dict

float

        For the specified concentrations of the chemicals in the decomposition reaction,
        determine its initial reaction's "rate" (aka "velocity"),
        i.e. its "forward rate" minus its "reverse rate",
        at the start of the time step.

        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6, "D": 19.9}
        :return:            The differences between the reaction's forward and reverse rates

name

arguments

returns

step_simulation

delta_time, conc_dict :dict, exact=False

(dict, float)

        Simulate the decomposition reaction A <-> B + C, over the specified time interval,
        using the "Forward Euler" method

        :param delta_time:  The time duration of this individual reaction step - assumed to be small enough that the
                                concentrations won't vary significantly during this span
        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"A": 1.5, "B": 31.6, "C": 19.9}

        :return:            The pair (increment_dict_single_rxn, rxn_rate)
                                - increment_dict_single_rxn is the mapping of chemical labels to their concentration CHANGES
                                                            during this step
                                - rxn_rate                  is the reaction rate ("velocity") for this reaction
                                                            (rate of change of either of the products)
                                EXAMPLE of increment_dict_single_rxn: "A": -1.3, "B": 2.9, "C": -1.6

name

arguments

returns

find_equilibrium_conc

conc_dict :dict

dict

        Determine the equilibrium concentrations that would be eventually reached
        by the chemicals of this reaction,
        given the specified concentrations,
        IN THE ABSENCE of any other reaction.

        :param conc_dict:   A dict mapping chemical labels to their initial concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6}

        :return:            A dict mapping the above chemical labels to their equilibrium concentrations

Class ReactionEnzyme

    Data about a SINGLE enzyme-catalyzed reaction that can be modeled kinetically as:

    E + S <-> ES -> E + P

        E : Enzyme
        S : Substrate
        ES: Intermediate Enzyme-Substrate complex
        P : Product

name

arguments

returns

__init__

enzyme :str, substrate :str, product :str, intermediate=None, k1_F=None, k1_R=None, k2_F=None, k2_R=None, kM=None, kcat=None, **kwargs

        :param enzyme:      The label for the chemical acting as enzyme
        :param substrate:   The reactant
        :param product:     The final reaction product
        :param intermediate:[OPTIONAL] The label for the reaction intermediate;
                                if not specified, the labels of the enzyme and substrate get concatenated.
                                EXAMPLE: "ES"
        :param k1_F:        [OPTIONAL]The forward reaction rate of the 1st part of the reaction
        :param k1_R:        [OPTIONAL]The reverse reaction rate of the 1st part of the reaction
        :param k2_F:        [OPTIONAL]The forward reaction rate of the 2nd part of the reaction
        :param k2_R:        [NOT IN USE]
        :param kM:          [OPTIONAL]"Michaelis constant"
        :param kcat:        [OPTIONAL]"Catalytic rate constant" aka "Turnover number" aka "Collective rate constant"
                            (equal to k2_F)

name	arguments	returns
describe	concise=False	str
Return as a string, a user-friendly plain-text form of the reaction :param concise: If True, less detail is shown :return: A string with a description of this reaction

name	arguments	returns
extract_reactant_labels		[str]
Return the list of ALL the reactant labels in this reaction, (including the enzyme) :return:

name

arguments

returns

extract_reactants

[(int, str)]

        Return a list of pairs with details of ALL the reactants of the given reaction
        (including the enzyme)
        Each pair contains stoichiometry and chemical label

        :return:    A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_reactants_formula		str
Return a string with a user-friendly form of the left (reactants) side of the reaction formula :return: A string with one side of a chemical reaction

name	arguments	returns
extract_intermediate		str \| None
Return the name of the reaction intermediate species, or None if there's no intermediate :return:

name	arguments	returns
extract_product_labels		[str]
Return the list of the labels of ALL the products of this reaction, (including the enzyme) :return:

name	arguments	returns
extract_products		[(int, str, int)]
Return a list of pairs with details of the products of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_products_formula		str
Return a string with a user-friendly form of the right (product) side of the reaction formula :return: A string with one side of a chemical reaction

name

arguments

returns

extract_chemicals_in_reaction

Set[str]

        Return a SET of the labels of ALL the chemicals appearing in this reaction,
        including enzyme and intermediate

        :return:    A SET of the labels of the chemicals involved in this reaction
                        Note: being a set, it's NOT in any particular order

name	arguments	returns
extract_rxn_properties		{}
Create a dictionary with the numerical properties of the given reaction

name

arguments

returns

compute_vmax

E_tot :float

float


        :param E_tot:   Total Enzyme concentration (bound and unbound enzyme);
                            at times referred to as E0
        :return:        The maximal reaction rate
                            (the asymptote of the rate, as the Substrate concentration grows large relative to Enzyme concentration)

name

arguments

returns

compute_rate

S_conc :float

float

        Based on the traditional Michaelis-Menten model.
        The argument may also be Numpy array.

        :param S_conc:  The concentration [S] of the (free) Substrate,
                            or a Numpy array of concentrations
        :return:        The corresponding reaction rate, in terms of production of the product P

name

arguments

returns

compute_rate_morrison

S_tot :float, E_tot :float

float

        Based on the Morrison model.
        Especially useful in scenarios with high concentrations of enzyme.
        The arguments may also be Numpy arrays.

        Reference: eqn 7.32 on page 124 of "Analysis of Enzyme Reaction Kinetics, Vol. 1",
                   by F. Xavier Malcata, Wiley, 2023

        :param S_tot:   The total concentration of free Substrate and Substrate bound to Enzyme
                            (i.e. [S] + [ES])
        :param E_tot:   Total Enzyme concentration (bound and unbound enzyme);
                            at times referred to as E0
        :return:        The corresponding reaction rate, in terms of production of the product P

name

arguments

returns

compute_k1_forward

kM, kcat, k1_reverse, verbose=False

        Compute and return the value for k1_forward, given kM, kcat and k1_reverse.
        Note that this is a linear affine transformation : k1_forward = k1_reverse * (1 / kM) + (kcat / kM)

        :param kM:
        :param kcat:
        :param k1_reverse:
        :param verbose:
        :return:

name

arguments

returns

compute_k1_reverse

kM, kcat, k1_forward: Union[float, np.ndarray], verbose=False

        Compute and return the value for k1_reverse, given kM, kcat and k1_forward
        Note that this is a linear affine transformation : k1_reverse = k1_forward * kM  - kcat

        :param kM:
        :param kcat:
        :param k1_forward:
        :param verbose:
        :return:

name	arguments	returns
min_k1_forward	kM :float, kcat :float	float
Return the minimum physically-possible value for k1_forward, for the given kinetic parameters kM and kcat :param kM: :param kcat: :return:

name

arguments

returns

set_thermodynamic_data

temp :float

None

        Set all the thermodynamic data derivable from the given temperature,
        and all previously passed kinetic and thermodynamic data.
        Raise an Exception if any inconsistency is detected.

        :param temp:    System temperature in Kelvins.

name

arguments

returns

step_simulation

delta_time, conc_dict :dict, exact=False

(dict, float)

        Simulate the enzymatic reaction E + S <-> ES -> E + P, over the specified time interval,
        using the "Forward Euler" method

        :param delta_time:  The time duration of this individual reaction step - assumed to be small enough that the
                                concentrations won't vary significantly during this span
        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"E": 1.5, "S": 31.6, "ES": 0.4, "P": 19.9}

        :return:            The pair (increment_dict_single_rxn, rxn_rate)
                                - increment_dict_single_rxn is the mapping of chemical labels to their concentration CHANGES
                                                            during this step
                                - rxn_rate pair             one value for each elementary reaction
                                EXAMPLE of increment_dict_single_rxn: {"E": 0, "S": -2.9, "ES": 0.1, "P": 2.8}

Class ReactionGeneric

    Data about a generic SINGLE reaction of the most general type,
    with arbitrary number of reactants and products,
    arbitrary stoichiometry,
    and arbitrary kinetic reaction orders for each participating chemical.

    IMPORTANT:  Use only for reactions whose dynamics can be satisfactorily modeled with kinetics involving
                the chemical concentrations raised to given powers.
                Do *NOT* use ReactionGeneric to model typical biochemistry enzymatic reactions
                of the type E + S -> E + P   (use the "ReactionEnzyme" class instead!)

    NOTE:   Simpler, more specific classes are available for Unimolecular Reactions (A <-> B),
            Synthesis Reactions (A + B <-> C), and Decomposition Reactions (A <-> B + C)

    Included:
        - stoichiometry
        - kinetic data (reaction rates, reaction orders)
        - thermodynamic data (temperature, changes in enthalpy/entropy/Gibbs Free Energy)
        - list of involved catalysts

    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 pair of the form: (stoichiometry coefficient, species label).
    Note that any reactant and products might act as catalyst.

name

arguments

returns

__init__

reactants :str|list, products :str|list, reversible=True, kF=None, kR=None, delta_H=None, delta_S=None, delta_G=None, kinetic_rate_function=ReactionKinetics.compute_rate_mass_action_kinetics, **kwargs

        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 pair:  (stoichiometry coefficient, chemical label

              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) - default stoichiometry coefficient of 1

              It's equally acceptable to use LISTS in lieu of tuples for the pairs

        :param reactants:   A list of terms that are either chemicals labels (with implied stoichiometry 1),
                                or pairs (stoichiometry coefficient , chemical label).
                                If not a list, it will first get turned into one
        :param products:    A list of terms that are either chemicals labels (with implied stoichiometry 1),
                                or pairs (stoichiometry coefficient , chemical label).
                                If not a list, it will first get turned into one
        :param kF:          [OPTIONAL] Forward reaction rate constant
        :param kR:          [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), in Joules
        :param kinetic_rate_function:  [OPTIONAL] Note - the current default will be removed in later versions
                                        EXAMPLES:  ReactionKinetics.compute_rate_mass_action_kinetics  (the generalized "standard rate law")
                                                   ReactionKinetics.compute_rate_first_order (reaction is first order in all reactants and products)

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

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

name

arguments

returns

extract_rxn_properties

{}

        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}

name	arguments	returns
extract_intermediate		str \| None
Return the name of the reaction intermediate species, or None if there's no intermediate :return:

name

arguments

returns

set_macro_enzyme

macromolecule: str, site_number: int

None

        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

name	arguments	returns
extract_catalyst		Union[str, None]
:return:

READ RXN DATA

name	arguments	returns
extract_reactants		[(int, str)]
Return a list of pairs with details of the reactants of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_reactants_formula		str
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

name	arguments	returns
extract_products		[(int, str)]
Return a list of pairs with details of the products of the given reaction, incl. their stoichiometry and chemical label :return: A list of pairs of the form (stoichiometry, chemical label)

name	arguments	returns
extract_products_formula		str
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

name

arguments

returns

unpack_for_dynamics

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, containing:
                        (reactants , products , forward rate constant , reverse rate constant)
                        Note: both reactants products are lists of pairs

name

arguments

returns

extract_chemicals_in_reaction

Set[str]

        Return a SET of the labels of ALL the chemicals appearing in this reaction

        :return:    A SET of the labels of ALL the chemicals involved in this reaction
                    Note: being a set, it's NOT in any particular order

name

arguments

returns

extract_reactant_labels

[str]

        Return the list of the labels of ALL the reactant in this reaction,
        (including any catalysts, if applicable),
        in the order in which they appear when the reaction was first defined

        :return:    List of chemical labels

name

arguments

returns

extract_product_labels

[str]

        Return the list of the labels of ALL the reaction products,
        (including any catalysts, if applicable),
        in the order in which they appear when the reaction was first defined

        :return:    List of chemical labels

DESCRIBE DATA

name

arguments

returns

describe

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 this reaction

ANALYSIS

name

arguments

returns

reaction_quotient

conc, explain=False

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 labels
                                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

name

arguments

returns

set_rate_function

None

        Set the function used to estimate the reaction rate (aka "velocity"),
        at the start of the time step.

        :param f:   A function that takes the following args:
                        reactant_terms :[(int, str)]
                        product_terms :[(int, str)],
                        kF :float, kR :float,
                        conc_dict :dict
                    and return a float
                    EXAMPLE:  ReactionKinetics.compute_rate_mass_action_kinetics
                              # Generalized "standard rate law"

        :return:    None

name

arguments

returns

set_thermodynamic_data

temp :float

None

        Set all the thermodynamic data derivable from the given temperature,
        and all previously passed kinetic and thermodynamic data.
        Raise an Exception if any inconsistency is detected.

        :param temp:    System temperature in Kelvins.  For now, assumed constant everywhere,
                            and unvarying (or very slowly varying).
                            If the temp gradually changes, periodically call this method.
        :return:        None

name

arguments

returns

determine_reaction_rate

conc_dict :dict

float

        For the specified concentrations of the chemicals in the generic reaction,
        determine its initial reaction's "rate" (aka "velocity"),
        i.e. its "forward rate" minus its "reverse rate",
        at the start of the time step.

        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6, "D": 19.9}
        :return:            The differences between the reaction's forward and reverse rates

name

arguments

returns

set_rate_constants_from_equilibrium_constant

None

        Set, as needed, a missing reaction rate constant (kF or kR)
        from the other one and the given equilibrium constant K.
        If all values already exist, and an inconsistency is detected, an Exception will be raised.

        Note: the reaction's equilibrium constant and its kinetic rate constants are
              in the relationship K = kF / kR for any reaction that follows "mass-action kinetics",
              i.e. whose reaction rates are proportional to the product of the reactants’ concentrations 
              raised to their stoichiometric coefficients

        :param K:   The reaction's equilibrium constant
        :return:    None

name

arguments

returns

step_simulation

delta_time, conc_dict :dict, exact=False

(dict, float)

        Simulate the generic reaction, over the specified time interval.
        The forward Euler method is used

        :param delta_time:  The time duration of this individual reaction step - assumed to be small enough that the
                                concentrations won't vary significantly during this span
        :param conc_dict:   A dict mapping chemical labels to their concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"B": 1.5, "F": 31.6, "D": 19.9}
        :param exact:       UNUSED - this option is unavailable
        :return:            The pair (increment_dict_single_rxn, rxn_rate)
                                - increment_dict_single_rxn     The mapping of chemical labels
                                                                    to their concentration CHANGES
                                                                    during this step
                                - rxn_rate                      The reaction rate ("velocity") for this reaction
                                EXAMPLE of increment_dict_single_rxn: {"B": -1.3, "F": 2.9, "D": -1.6}

name

arguments

returns

find_equilibrium_conc

conc_dict :dict

dict

        Determine the equilibrium concentrations that would be eventually reached
        by the chemicals of this reaction,
        given the specified concentrations,
        IN THE ABSENCE of any other reaction.

        :param conc_dict:   A dict mapping chemical labels to their initial concentrations,
                                for all the chemicals involved in this reaction
                                EXAMPLE:  {"X": 4.3, "Y": 1.5, "F": 31.6, "G": 3.6}

        :return:            A dict mapping the above chemical labels to their equilibrium concentrations