# Reaction Editor

The identifier and name for a reaction are analogous to those for a species. By default the name field is hidden. Specify the reactants and products by typing the species identifiers preceded by their stoichiometries. For example: "s1", "s1 + s2", "2 s2", or "2 s1 + s2 + 2 s3". The stoichiometries must be positive integers. A reaction may have an empty set of reactants or an empty set of products, but not both. (A "reaction" without reactants or products has no effect on the system.) The `MA` field indicates if the equation has mass-action kinetics. In the `Propensity` field you can either enter a propensity factor for use in a mass-action kinetic law or you can enter an arbitrary propensity function. The reactions editor has the same tool bar as the species editor. Again, you will be informed of any bad input when you try to launch a simulation.

If the `MA` field is checked, a reaction will use a mass-action kinetics law. For this case you can enter a number or a Python expression that evaluates to a number in the `Propensity` field. This non-negative number will be used as the propensity factor in the reaction's propensity function. Below are some examples of reactions and their propensity functions for a propensity factor of k. [X] indicates the population of species X. The population is measured in substance units, for example number of molecules, and not in concentration units. (In the table below 0 indicates the empty set; either no reactants or no products.)

    Reaction   Propensity Function
    -------------------------------
    0 → X      k
    X → Y      k [X]
    X + Y → Z  k [X] [Y]
    2 X → Y    k [X] ([X] - 1)/ 2

If the `MA` field is not checked the `Propensity` field is used as the propensity function. For example, you might to use a Michaelis-Menten kinetic law. Use the species identifiers to indicate the species populations. You can use any model parameters in defining the function. The format of the function must be a C++ expression. (Don't worry if you don't know C++. Just remember to use * for multiplication instead of a space. Also, if you divide by a number use a decimal point in it. For example, write "5/2." or "5/2.0" instead of "5/2". Integer division instead of floating point division will be used in the third expression resulting in 2 instead of 2.5.) Below are some examples of valid expressions for propensity functions. Assume that the species identifiers are s1, s2, ...

    C++ Expression   Propensity Function
    ------------------------------------
    2.5              2.5
    5*pow(s1, 2)     5 [s1]2
    1e5*s2           100000 [s2]
    P*s1*s2/(4+s2)   P [s1] [s2] / (4 + [s2])
    log(Q)*sqrt(s1)  log(Q) √[s1]

Here we assume that `P` and `Q` have been defined as parameters. Note that you do not have to use the `std` namespace qualification with the standard math functions like `sqrt`, `log`, and `exp`. The expressions will be evaluated in a function with a `using namespace std;` declaration.

Most of the stochastic simulation methods store the values of the propensity functions and recompute them only when the values change. (This innovation was introduced with the next reaction method.) If firing a certain reaction modifies a species X then any propensity that depends on X must be recomputed. For mass-action kinetic laws, the propensity function depends on the reactants. Thus we use the reactants to determine the reaction dependencies.

There is a technical issue with custom propensities when simulating a model with a stochastic method: If one uses a species population in the propensity function, then that species must appear as a reactant. Otherwise the reaction dependencies will not be determined correctly. For example consider a system with two species X and Y. Suppose one had the reaction 0 → X with the custom propensity Y. Of course the propensity does not make physical sense, but that is beside the point. Cain will not allow this reaction. Attempting to launch a stochastic simulation will produce an error message. (One can, however, run a deterministic simulation.) To ammend the reaction one must add Y as a reactant (and as a product so as to leave the kinetics unchanged). The reaction Y → X + Y is allowed. Physically speaking, Y is a substrate.