Testing and Troubleshooting Reaction Schemes

Although the simulation method Kinetiscope uses is reliable, some choices of settings can affect your simulation results, calculation times and file size.

Some Basics to Check

  1. Be sure that you have specified enough particles for the full dynamic range of concentrations in the reacting system. To check, try doubling and halving the number of particles, and comparing the simulation results. You have enough if doubling the number does not change the concentration vs time curves.
  2. If your print interval is too large, you may miss structure in your simulation results, or it may appear that the simulation is not following your temperature/voltage/external stimulus profile properly. The state of the system is accurate at all times in memory, but the saved data may not show the results you expect. Decrease the print interval until you are satisfied with the appearance of your simulation results.
  3. Be sure you are plotting all the available data points. The default behavior is to display 1000 points regularly spaced through the calculated results; this may appear to distort or hide fine structure in the calculated results.
  4. Check for typing errors in all your input data. If species mnemonics are mistyped, they will be tracked as separate species and those reaction steps will have incorrect rates. If a thermochemical or density value is wrong, the simulation results will be incorrect. Errors in rate constants also strongly affect the calculation.

Tools for Testing

Kinetiscope includes a number of features that assist you in choosing simulation settings. These include

Explicit display of the number of molecules represented by each particle.
On the Simulation Settings Page the Total Number of Particles data entry field displays the number of molecules each particle represents. This value is calculated by dividing the total number of molecules defined in the reaction scheme by your entry in the data entry field.
Explicit display of the number of particles apportioned for a species' initial concentration.
When Kinetiscope initializes a simulation, it apportions particles to represent molecules in proportion to their amounts; their amounts in turn depend on the initial concentrations of each species in a compartment and that compartment's initial volume. When you enter an initial concentration either in the Compartment Editor Dialog or a Species Data Page, Kinetiscope displays the number of particles to be apportioned to that species.
Explicit tracking of selection frequencies of each step.
Kinetiscope selects a reaction step or transfer step to be advanced based on its instantaneous probability. In a complex scheme it may be difficult to ascertain by inspection that all steps are active in the expected way. By enabling this function (from the Application Options Dialog) Kinetiscope will record how often each step is selected and will save that data for your evaluation. You view this information for a single compartment or transfer path using a frequency plot window, and you can view in a histogram format the selection frequencies for all steps in the reaction scheme using a selection frequency histogram window.
Text listings of compartments, transfer paths and reaction schemes.
Use the Show Text Listing Dialog to examine the contents of these in a single text document. You create and view a text listing by selecting the View Text Listing of... menu item from the context menu that appears when the right mouse button is clicked over an empty reagion of a scheme diagram, or over one of the compartments or transfer paths in that scheme diagram.

Some Common Issues

Programmed temperature/voltage/stimulus simulation gets stuck at one point in time.
This may be an indication that the Total Number of Particles value on the Simulation Settings Page is too small. Increase the value by a factor of ten and restart the simulation.
The electrochemical steps are not active.
Be sure that you have defined an electron transfer step in at least one of the transfer paths attached to the compartment. You use the Transfer Path Editor Dialog to add a new transfer step and the Transfer Step Editor Dialog to set the new step as an electron transfer.

Be sure that the Voltage option is turned on the Reaction Conditions Page.

The volume does not change in my variable volume simulation.
Be sure that you have indicated, for each compartment whose volume may vary, which dimensions are unconstrained and free to change. You set this on the Compartment Details Page of the Compartment Editor Dialog.

Also check that the Variable Volume option is enabled on the Reaction Conditions Page.

The simulation is slow.
Simulations of some reaction schemes by their nature can take some time to complete; for example, large schemes with thousands of compartments, schemes with rapidly maintained chemical equilibria and rapid reversible transfer steps may require longer-than average simulation times. In such cases, it can be beneficial to carry out initial trial simulations using a low value for the Total Number of Particles, and then increase that value for a final longer simulation with lower random statistical noise.

In many instances however, simulation time may be reduced by

  • Enabling the Equilibrium Detect option on the Simulation Settings page if rapid equilibria may be present.
  • Reducing the Total Number of Particles on the Simulation Settings page.
  • Rewriting bimolecular reaction steps where one reactant is present in great excess as pseudo-first order reactions. To do this, you multiply the bimolecular rate constant by the concentration of the reactant in excess; edit the reaction equation to eliminate the reactant and enter this value as the first order rate constant using the Reaction Step Editor Dialog.
  • Adjusting rate constants for rapidly maintained equilibria. Equilibrium reactions in Kinetiscope are represented as reversible steps with forward and backward rate constants kfwd and krev. The equilibrium constant Keq is related to these by

    Keq  =  kfwd

    By dividing both kfwd and krev by equal factors, their ratio Keq is maintained but their probabilities of selection are proportionately decreased. You must, of course, confirm that the equilibrium still is adequately maintained with the reduced rate constants.
In a volume plot window, the compartments in the foreground hide those within the plot.
It is often best to use a monochrome color map with low opacity to be able to see into the interior of a volume plot window. You select the color map and opacity from the Attributes Page of the Three-Dimensional Plot Settings Dialog. Use the plot's context menu to access the dialog.