STEM newsletter

How does auditing work?

30 July 2003

STEM delivers huge benefits through its ability to rapidly generate reliable and detailed calculations for dynamically developing model structures. However, this productivity gain necessitates a ‘black box’ aspect which may concern those used to tracing calculations line-by-line in a spreadsheet. This latest technical article explains the meticulous preparation which enables STEM to lead both modeller and client to the most critical calculations in a model.

Why did it do that?

Business-case models are designed to encapsulate the complexities of service description, network dimensioning and lifetime costing in order to explore the impact of strategic decisions on business outcomes. Almost by definition, the results of any significant model may occasionally defy immediate explanation. In a spreadsheet, you can always trace through precedent arrows to methodically analyse the relevant calculation path(s), but this may involve the interpretation and assessment of myriad formulae and typically ubiquitous cell references, which can be especially challenging if you are not the author of the sheet in question.

In contrast, the consistent calculations in a STEM model significantly simplify the domain of immediate influence on a given result. In principle, a clear view of model structure (almost guaranteed by STEM’s intuitive iconic presentation), coupled with a thorough understanding of standard algorithms, is all you need to understand even the most unusual result. However, modern requirements for openness and review demand that the software should speak for itself when necessary, and this is the philosophy behind the intrinsic audit system which is built into the STEM model engine.

Consider the following example. A Service with demand growing by 1000 every year from 2004 requires a resource with capacity 400. Hovering over each icon in turn with the mouse reveals an automatic summary of the key inputs, from which the simplest expectation would be for the number of installed units of the resource to increase by two or three (1000 / 400) each year.

In fact the results tell a different story, showing that in fact six units are installed in 2004:

Installed Units is a primitive result, so what to do? Why did it do that? The answer is better than tracing through formulae; it is closer to “Tell me!” Select Audit from the resource icon menu, and then simply select Installed Units from the list of primitive results.

Now run the model again, and immediately a message pops up for 2003. It seems the modeller has requested some pre-installation of equipment. Press OK to continue.

Planned unit audit for 2003

For 2004 we first see details of the basic incremental demand calculation, but then also deployment. Yes, this resource is also linked to a Location which describes a number of geographical sites. But it doesn’t stop there. Other factors, such as maximum utilisation or supply ratio might influence the installation of the resource, but the guiding principle is that you don’t have to know how the result is calculated, STEM will tell you, and why!

Incremental demand and deployment audits for 2004

The comprehensive list of auditable primitive results is complemented by a number of labels prefixed with an asterisk, such as Incremental Demand. These labels correspond to specific stages of calculation, and map directly onto the intrinsic audit features. When you select a result name, you are taking advantage of an internal mapping of individual results onto each of the stages of calculation which directly affects it.

Labels with asterisks correspond to specific stages of calculation

By default, the audit system will generate an interactive audit as described above for each period of the model run, and for all selected results for any number of elements. There is also a global Audit dialog (select Audit from the Data menu on the main Editor window) which allows you to confine auditing to a specific range of run periods, and to suppress the interactive messages. All audit data are written to a model.audit.txt file which STEM will load into Notepad on completion of the model run. It is quite instructive to generate a full audit (all results for all elements for all periods) to get a sense of the breadth of calculations being performed, even for a simple model!

Where did this come from?

When STEM runs a model, the STEM model engine first creates a calculation structure for the propagation of demand from Services to Resources and through intermediate Transformations, and then performs all the necessary incremental demand, revenue and cost calculations for each period of the model run. These primitive results are stored to disk each run period, and then sorted into series order after the model run to create a sorted model results file (.SMR)

Many additional results (especially financial) are then calculated on demand in the results program, from an extensive set of pre-programmed result definitions in DEFAULT.CNF. These results are called derived results, and it is this mechanism which enables you to add your own custom results, automatically instantiated for all elements (and Collections) of a given type. (Select Define Results… from the Config menu).

When looking at any graph in the results program, press <F1> to access the online help. Interpretation is provided for all standard results, together with a human explanation of how each individual result is calculated, with references to related results and links through to detailed explanations of particular model features (algorithms). (No distinction is drawn between the primitive results and derived results in this context.)

Online help interprets and explains calculation of all standard results

The online help tells you generically how a results is calculated, but not the specific data, and so this facility is complemented by the Draw Precedents command on the Graph menu. Again, when looking at any graph in the results program, press <F2> to graph all of the numbers from which a current result is calculated. The precise formula used or the calculation is shown in the status bar. If the results is a network result summed over services or resources, you will be prompted to make a selection from all of the relevant elements.

Draw Precedents shows the formula for, and data from which, a result is calculated

Thus all derived results can be traced back directly to the set of primitive results generated by the model engine, dove-tailing perfectly with the run-time audit described above.

How does it all fit together?

By now you will have the sense that, far from being a black box, all of the calculations of STEM model results are readily accessible. The most common remaining obfuscation is unfortunately self-inflicted. It can happen that a result hypothesis is based on a unalienable assertion that only certain elements are involved in a given calculation. Multiple views in the Editor are great for breaking up structure into manageable chunks (indeed one of Robin’s favourite maxims is about avoiding the need for scrolling individual views) but they can also obscure certain relationships.

When in doubt, the Editor provides a range of commands for creating a temporary debugging view which guarantees to reveal all structure:

  • Select Show In A New View from the Resource icon menu to create a new view surrounding just this element. (Tip: useful to maximise next.)
  • Select Show Precedents from the icon menu. Our original Service is now revealed, with its requirement for this Resource.

  • Select Show Hierarchy from the Resource icon menu. Now the Location is revealed.
  • Select Show Dependents from the Resource icon menu. A status message reads “0 dependent elements found”. So now we know that, for example, no Transformations reference this Resource as an input.

Additional commands allow you to reveal all direct links, or all levels of precedents, dependents or hierarchy (such as Collections and Functions). This view may quickly become cluttered, and you will begin to appreciate the elegance of the original view after all. However, all is not lost. You can arrange either a selection or all visible icons in order of precedence, just select Arrange Selection/Visible… from the Element menu.

Icons may be laid out horizontally or vertically, and you can choose whether to consider either run-time dependencies (such as a Resource requirement) or static dependencies (internal references in formulae in the Editor) or both. In addition, you can create a comprehensive and ordered view of an entire model by selecting Show and Arrange All… However, the Editor does not attempt to generate an artistic transverse layout, so this is generally less helpful than the selective approach.


All of the features described in this article are used routinely by STEM support staff when responding to customer enquiries. At least 95% of all such queries (already pre-qualified as ‘difficult’) are resolved without recourse to source-level debugging or undocumented insights. We hope that this article will help you to help yourself next time you can’t quite figure something out. Then we’ll have to design a predictive system which allows you to ask, for a given set of desired results, “How could I do that?”

© Implied Logic Limited