Tips for Debugging a GoldSim Model

Issue

How do I debug a GoldSim model? What approach should I take?

Resolution

All of us at some point have built a GoldSim model, run it, and found that the results don't seem to make any sense. Of course, we often like to immediately conclude that the problem is due to a software bug (and sometimes it is!). However, in the overwhelming majority of cases, the problem is due to a logic error in your model. So how do you go about debugging such a model?

Although debugging (whether in GoldSim or any modeling tool) is typically something that each individual develops their own approach for, there are several general rules you can follow and suggestions you might use to make the process more efficient.

First of all, before starting to debug or test a model, in general there are two key things you should NOT do:

1. Don't try to debug a probabilistic model. Monte Carlo results are typically too complex to facilitate debugging. If you suspect that something is wrong with a Monte Carlo result, you should run the model deterministically (either in deterministic mode or by running a single specified realization that you suspect has a problem). The bottom line here is that you first should also start debugging a model by looking at single realizations.

2. If you are using the Radionuclide Transport Module for contaminant transport modeling, when first testing a model, you should NOT activate species decay and ingrowth. GoldSim provides an option (in the Options dialog) to temporarily deactivate decay. This makes it much simpler to determine if you have built a mass balancing model.

So what techniques can be used to debug a model? Unfortunately, there are no silver bullets. It simply takes careful analysis and testing. In most cases, debugging will consist of viewing time histories of key variables. It is often useful to plot multiple time histories on one plot. More often than not, after viewing trends in plots, you may want to switch to Table view to display that actual values at each timestep. Careful analysis of time histories is the most powerful debugging tool you can use. A few suggestions in this regard:

Create a number of "warning expressions" that when true, indicate a logical error in your model. For example, if a value cannot logically be negative, create a conditional expression (e.g., X < 0) and track this. As will be discussed below, an upcoming version of GoldSim will provide an even more powerful way to accomplish this.

Use Time History Result elements for plotting time histories that you are evaluating as part of the debugging process. This allows you to easily re-run and view a group of time histories.

Note that a Time History Result element can only accept outputs with two different dimensions. This means that you may need to create several Result elements (and open them both) to view multiple time histories at the same time.

Another useful debugging tool is GoldSim's Sensitivity Analysis feature. When running a sensitivity analysis, GoldSim holds all inputs constant (at their specified deterministic value), and varies parameter that you specify over a specified range. So if you suspect that the model is not handling a particular parameter in a logical way, you can run a sensitivity analysis and vary that parameter (while holding others constant) in order to determine how that parameter impacts some result in your model.

In the upcoming summer release of GoldSim, a new element (the Interrupt) will be provided. An Interrupt element will be a powerful debugging tool. In an Interrupt element, you specify a trigger (e.g., a condition such as X > Y). When the Interrupt is triggered, it pauses the model and displays a user-defined message (e.g., " X should never be greater than Y. Something is wrong with this model"). The message will include a button that directs the user to a specified element (e.g., X or Y).

As a final note, the most important thing you can do to make your models easier to debug is to organize and document them well. A poorly organized and documented model is always more difficult to debug. That is, a well-organized and documented model is not only much more effective to present, it is likely to save you lots of time if you need to debug it