The model and all files associated with its calibration are available by clicking here.

The Model

The model being used is the simple SIR model first presented in my blog post Limits to Growth. The model is shown again below. There are two parameters: infection rate and recovery rate. Technically, the initial value for the Susceptible stock is also a parameter. However, since this is a conserved system, we can make an excellent guess as to its value and do not need to calibrate it.

The Data Set

We will calibrate this model to two data sets. The first is the number of weekly deaths caused by the Hong Kong flu in New York City over the winter of 1968-1969 (below).

The second is the number of weekly deaths per thousand people in the UK due to the Spanish flu (H1N1) in the winter of 1918-1919 (shown later).

In both cases, I am using the number of deaths as a proxy for the number of people infected, which we do not know. This is reasonable because the number of deaths is directly proportional to the number of infected individuals. If we knew the constant of proportionality, we could multiply the deaths by this constant to get the number of people infected.

Preparing the Model

The original model ran from 0 to 40 days. This needs to be changed to match the data, i.e., to 1 to 13 weeks. Changing this will force us to change the parameter values also, as described below.

The initial values of Susceptible and Infected must be changed to match the data set. The total number of people in the model should match the total population in the data. Summing the Hong Kong flu data set gives a population of 1035 people. The initial value for Infected is just the first reported value, 14. That leaves 1021 people that are Susceptible.

If you run the model using the original parameter values, you will find the infection is spreading far too quickly. To improve the chances of the calibration succeeding, it is necessary to adjust the parameters so that the results are in the ballpark of the historical data. To do this, it is useful to paste the historical data into a graphical function (called data in this model) and graph it alongside the model output. I first reduced the infection rate from 0.005 to 0.0015 and then adjusted recovery rate from 0.25 to 0.5 to get a closer fit to the data.

The model must also be modified to persistently import its parameters and export the time series we wish to fit to the historical data. The import sheet is most easily set up by creating an empty CSV file, exporting “all model variables” and “One set of values” to this file, and then removing the variables that are not needed from this file. The file can also be built manually. The final file, input.csv, looks like this:

infection rate,recovery rate
0.0015,0.5

You will also need to create an empty file called output.csv for the exported data.

Set up the import by choosing Edit->Import Data… and entering the settings shown below:

Add a table, called Table 1, to the model and add the stock Infected to the table. Set up the export by choosing Edit->Export Data… and entering the settings shown below. Note the “Use table settings” option is not used. This option cannot be used for calibration as it will restrict to precision of the output to match the table.

Save the model. It is ready to be calibrated.

Setting up PEST

PEST is a very powerful program. This post will only touch on the simplest capabilities that it provides. For more details and for more complex uses, consult the PEST manual.

PEST requires three text input files:

• The template file (.tpl), which tells it how to write the parameters to the model input file (input.csv in our case).
• The instruction file (.ins), which tells it how to read the data from the model output file (output.csv in our case).
• The control file (.pst), which tells PEST what to do.

Creating the Template File

This is the simplest file to create, as it only requires replacing data values in the model input file with markers so PEST can insert the parameter values it chooses.

Open the model input file, input.csv, in a text editor. Add the following line to the top of the file:

ptf #

This tells PEST this is a template file and that parameter fields, including the parameter name, will be surrounded by pound signs (#).

Replace each parameter value in the file with a short alphanumeric name for that parameter, surrounded by #s. Add any additional spaces that are necessary to make each field 13 characters long, including the pound signs. Using 13-character field widths, which is the maximum precision in single-precision floating point, is absolutely necessary to make certain the calibration succeeds (see end note about precision).

Save this file as input.tpl. The final file should look like this:

ptf #
infection rate,recovery rate
#infectrate #,#recoverrate#

Creating the Instruction File

The instruction file contains a set of instructions that PEST can follow to extract the model-generated data that corresponds to the historical data from the model output file. The model output file is a CSV file that has a header line followed by 13 lines, one for each week in the model run. Each of the 13 lines contains two numbers separated by a comma. The first value on each line is the week number and the second is the number of people who have been infected.

The contents of the instruction file, output.ins, appear below:

pif @
l2 @,@ !infected1!
l1 @,@ !infected2!
l1 @,@ !infected3!
l1 @,@ !infected4!
l1 @,@ !infected5!
l1 @,@ !infected6!
l1 @,@ !infected7!
l1 @,@ !infected8!
l1 @,@ !infected9!
l1 @,@ !infected10!
l1 @,@ !infected11!
l1 @,@ !infected12!
l1 @,@ !infected13!

The first line tells PEST that this is an instruction file and that the at-sign (@) will be used to delimit search keys. Each succeeding line tells PEST how to read the model output file, output.csv.

Each instruction line starts with a lowercase L, the PEST command to skip to the beginning of the Nth following line. The number one (1) is used to move to the start of the next line (interpreted as the start of the first line when at the beginning of the file), while larger numbers skip over an additional N – 1 lines. Thus, the “l2” in the first command, moves to the start of the second line in the file, skipping over the header. Each additional command uses “l1” to move to the start of the next line.

On every single line, it is necessary to skip to the second field (Infected), as we do not care about the week number. Surrounding the comma in at-signs (@,@) tells PEST to move to the next comma it finds (which will be the first comma on the line in all cases shown here). The exclamation points (!) delimit the name of the observation (historical data point) that corresponds to the data after the comma (called observation names in PEST). Note that each value of a time-series requires a unique observation name and that each observation name cannot be longer than 20 characters. In this case, there are 13 values, one for each week, in our historical data and our model-generated data, so the variables are named infected1 thru infected13.

In many cases, there will be far more data values that need to be assigned names. The instructions in this file, including the ever-incrementing names, can be quickly created in some text editors and also in Excel. The following formula can be pasted into cell A1 of Excel and filled down as far as necessary to create the proper instructions:

=CONCATENATE(“l1 @,@ !infected”, ROW(A1), “!”)

The above instruction names uses the name infected as the root of all observation names. Make sure to change this name in the above formula to match the variable name in your model. After you copy the text generated by Excel into your instruction file, make sure to change the first command so that it begins with “l2” rather than “l1”. If you fail to do this, PEST will not skip over the header in output.csv and will abort when it tries to read numeric values from the text that appears there.

There will also be cases where it is desirable to calibrate to multiple pieces of data. In this case, the commands in the instruction file will have to be modified to include the additional data. For example, if there is a second historical time series Treated and Treated appears after Infected in the model output file, each command would change to (using the fifth value as an example):

l1 @,@ !infected5! @,@ !treated5!

Creating the Control File

The control file contains a number of PEST parameters, the historical data, the command to run the model, and the names of the other files needed by PEST. It is a difficult file to create on your own. Luckily, PEST provides some command line tools to help. In particular, PESTGEN will generate the control file (with default settings) from two simpler text files:

• The parameter file (.par), which lists the input parameters to the model
• The observations file (.obf), which lists the historical time series; INSCHEK can generate this from the model output file and the instruction file Both files are fixed-format, which means the field widths and alignment must be properly respected. It is easiest to create the parameter file by editing an existing parameter file (PEST outputs a parameter file containing the final parameter values at the end of a calibration; the file used for this calibration is also included with the model).

The parameter file for this model, hkflu.par, appears below.

  single point
    infectrate    1.5000000E-03     1.000000         0.000000
   recoverrate    0.5000000         1.000000         0.000000    

The first line tells PEST to use single-precision floating point and to always include the decimal point when writing parameters to the model input file. The file then contains one line for each input parameter.

Each line starts with the name of the input parameter, as it appears in the template file, right-justified. This is followed by the initial value of that parameter, a scale factor (normally one) and an offset (normally zero). To add additional parameters, copy and paste the lines and make sure the columns line up with the existing lines.

The observations file contains all of the observation names with the historical data values for each. The command line tool INSCHEK, which comes with PEST, will generate this file by merging the observation names in the instruction file with data in a file formatted the same as the model output file. The instruction file has already been created. To complete this process, copy and paste the historical data into the second column (Infected) of the model output file, output.csv, and save it. Open the Windows command prompt window by choosing “Command Prompt” under All Programs->Accessories. Make sure to change the current directory to the directory containing your model and your PEST files. This is easily done by type “cd ” (the ending space is necessary) and then dragging the folder icon in the address field of the Windows Explorer window for that folder onto the command window. Reselect the command window and press Enter. The directory is now set. Now type:

inschek output.ins

Note that inschek will need to be preceded by the path to the PEST directory if you have not added the PEST directory to your PATH environment variable. This command will verify there are no syntax errors in your instruction file. If you get any errors, correct them and check again. Continue until there are no errors reported. Then type:

inschek output.ins output.csv

This will create the observations file, output.obf, from the data you pasted into output.csv.

It is now possible to create the control file, hkflu.pst. Type:

pestgen hkflu hkflu.par output.obf

If there are errors reported in the parameter file, fix them and try again. This command generates a default control file for case hkflu (short for Hong Kong flu – you can name it anything you want) with your parameter values and historical data. This file will require some editing before PEST can be run.

Editing the Control File

The generated file looks like this (to view, right-click on hkflu.pst, choose “Open With…”, and select WordPad):

pcf
* control data
restart  estimation
    2    13     2     0     1
    1     1 single point   1   0   0
  5.0   2.0   0.3  0.03    10
  3.0   3.0 0.001
  0.1
   30  0.01     3     3  0.01     3
    1     1     1
* parameter groups
infectrate   relative 0.01  0.0  switch  2.0 parabolic
recoverrate  relative 0.01  0.0  switch  2.0 parabolic
* parameter data
infectrate   none relative   1.500000E-03  -1.000000E+10   1.000000E+10
 infectrate     1.0000        0.0000      1
recoverrate  none relative   0.500000      -1.000000E+10   1.000000E+10
 recoverrate     1.0000        0.0000      1
* observation groups
obsgroup
* observation data
infected1      14.0000      1.0  obsgroup
infected2      28.0000      1.0  obsgroup
infected3      50.0000      1.0  obsgroup
infected4      66.0000      1.0  obsgroup
infected5      156.000      1.0  obsgroup
infected6      190.000      1.0  obsgroup
infected7      156.000      1.0  obsgroup
infected8      108.000      1.0  obsgroup
infected9      68.0000      1.0  obsgroup
infected10     77.0000      1.0  obsgroup
infected11     33.0000      1.0  obsgroup
infected12     65.0000      1.0  obsgroup
infected13     24.0000      1.0  obsgroup
* model command line
model
* model input/output
model.tpl  model.inp
model.ins  model.out
* prior information

This is also a fixed-format file, so you need to be careful when editing it. Luckily, only a few things need to be edited.

The “pcf” at the top of the file tells PEST this is a control file. The control data section sets a number of parameters that can stay the way they are unless the calibration does not work (in which case, you will need to dig deeply into the PEST manual to figure out what to change and how to change it). The parameter groups section, the observation groups section, and the observation data sections will not require any changes. However, the parameter data section needs to be adjusted and both the model command line and model input/output need to be specified.

For each parameter under parameter data, you must decide whether the changes made by PEST to the parameter will be relative (i.e., additive – the default), or factor (i.e., multiplicative). There are advantages and disadvantages to each, however, for a STELLA model, this simple guideline should help: change all time constants, rates, and multipliers to factor. In the SIR model, both variables are rates, so the word “relative” must be replaced with “factor ”. Note the two extra spaces after “factor”; the new text must completely fill the space formerly occupied by “relative”.

The default domain for each parameter is set to -1.0e10 to 1.0e10. You are likely to have better information (especially if it is a multiplier) and should enter it here in place of those numbers. I restricted the domain of infectrate to between 0.0001 and 0.01 and that of recoverrate to between 0.01 and 1.0. This was based on both my knowledge of these variables and some simple experiments I ran. The domains for these parameters could be much wider, as long as they stay above zero in both cases. This leads to the following changed lines (truncated after limits):

infectrate   none factor     1.500000E-03   1.000000E-04   1.000000E-02 …
recoverrate  none factor     0.250000       1.000000E-02   1.000000E+00 …

The model command line is changed to:

run.bat

The batch file run.bat contains commands to create the model output file and to run the STELLA SIR.stm model:

@echo off
echo > output.csv
start /min /wait “” “C:\Program Files\isee systems\STELLA 9.1.4\STELLA” -r SIR.stm

If STELLA was not installed to the default directory shown in the above command, run.bat will need to be edited to contain the correct path to STELLA.  The model output file needs to be recreated in the batch file (using echo) because PEST deletes the model output file before running the model.

Finally, the model input/output section was changed to name the template, model input, instruction, and model output files. Note these are not fixed-width fields.

input.tpl  input.csv
output.ins output.csv

Running PEST

Before running PEST, it is a good idea to verify that all of the input files are valid. This is accomplished with PESTCHEK:

pestchek hkflu

Fix any errors that are reported and repeat until all errors are gone. Note that PESTCHEK does not require the case name (hkflu) to be specified. Without the name, it will find all case names in the current directory (by searching for PEST control files) and check them all.

Finally, start the calibration process with:

pest hkflu

PEST will run until it detects no further changes or cannot proceed. Each iteration, it will report a value named phi. This is the sum of the squared residuals and should be decreasing each iteration. If PEST succeeds, the model input file will contain the best parameter values found and the model output file will contain the results obtained with those parameter values.

PEST outputs a number of files as well. As already discussed, the parameter file (.par) will be updated (or created) to contain the final successful parameter values. The run details file (.rec) will contain a log of the search, including parameter values tried and their relative success, as well as the final results compared to the historical data, with residuals. The 95% confidence interval for the parameters is also given. A number of other files are generated by PEST. See the PEST manual for further details.

The results of running PEST with this model and these initial parameters are shown in the graph below. The final parameter settings discovered by PEST were infection rate = 0.0015766646 and recovery rate = 0.82166505, with a final error (phi) of 4785.7 (compared to 773,059 with the original parameters).

Changing the Data Set

Shown below is the number of weekly deaths per thousand people in the UK due to the Spanish flu (H1N1) in the winter of 1918-1919.

To calibrate to this data set, it is necessary to change the initial values of the Susceptible and Infected stocks in the model. The historical data values in the PEST control file must also be changed.

The initial value of Infected is, again, the first data value (1 in this case). The initial value of Susceptible is, again, the remaining population (148). The model SIR2.stm contains these changed settings, as well as the new historical data set.

While it is relatively easy to regenerate and edit the PEST control file, it is just as easy to edit the few historical values. Control file spflu.pst contains the new dataset. It also uses run2.bat to run SIR2.stm instead of SIR.stm. Type:

pest spflu

Although it takes some time, the calibration almost succeeds using the same starting parameters as those for the Hong Kong flu. It fails in the end because the domain of infection rate is too narrow; infection rate gets stuck at 0.01. It is important to note that PEST reported success in this case. Looking at the graph in STELLA, however, made it clear that it only came close, while looking at the chosen parameters showed the boundary was reached. Changing the maximum value to 0.1 in spflu.pst fixed that problem. The final results are shown below.

This was generated with infection rate = 0.012101631 and recovery rate = 0.89054160. The error decreased from 2233.8 at the start to 110.6 with these parameters.

Troubleshooting PEST

Chapter five of the PEST User Manual includes a detailed troubleshooting section titled “If PEST Won’t Optimize.” If PEST is not changing parameters or not succeeding, this section will help you discover why.

Troubleshooting Data

In the examples used in this post, the model-generated data was one-to-one with the historical data. In many cases, data is not collected at a set frequency, does not coincide in time with model-generated data, and there are missing data points. While this was not covered in this example, PEST is capable of dealing with these cases. Missing data points can be handled by using !dum! as a placeholder in the instruction file (or additional lines can be skipped between points). PEST can also interpolate the model-generated data to match it in time to the historical data. Refer to the PEST manual for instructions to handle these cases.

End Note (about precision): While STELLA and iThink use double-precision for its calculations and PEST supports double-precision output, it is not possible to directly interface to PEST in double-precision mode as PEST outputs exponentials using “D” instead of “E” when in double-precision mode (as FORTRAN does). Such non-standard numeric formats cannot be read by STELLA. Double-precision can be used if necessary by adding a preprocessor to convert those “D”s in the model input file to “E”s before running STELLA and by adding a post-processor after running STELLA to change the “E”s output by STELLA to “D”s. Each parameter should also be given a field that is 23 characters wide, instead of 13, in the template file. Most applications will not need to use double-precision.

The DT setting is found in the Run Specs menu.

By definition, system dynamics models run over time and DT controls how frequently calculations are applied each unit of time.  Think of it this way, if your model was a movie, then DT would indicate the time interval between still frames in the strip of movie film.  For a simulation over a period of 12 hours, a DT of 1/4 (0.25) would give you a single frame every 15 minutes.  Lowering the DT to 1/60 would give a frame every minute.   The smaller the DT is, the higher the calculation frequency (1/DT).

Beware of the Extremes

A common tendency for modelers is to set the calculation frequency too high.  Without really thinking too hard about it, more data seems to imply a higher quality model – just like more frames in movie film make for smoother motion.  If your model calculates more data for every time unit, its behavior will begin to resemble the behavior of a smoothly continuous system.  But a higher frequency of calculations can greatly slow down your model’s run performance and more data does not directly translate to a better simulation.

Beware of Discrete Event Models

Another situation where DT can often lead to unexpected behavior is with models that depend on discrete events.   My eyes were opened to this when I attended one of isee’s workshops taught by Corey Peck and Steve Peterson of Lexidyne LLC.

One of the workshop exercises involved a simple model where the DT is set to the default 0.25, the inflow is set to a constant 10, and the outflow is set to flush out the stock’s contents as soon as it reaches 50.   This is how the model’s structure and equations looked:

Stock = 0

inflow = 10

outflow = IF Stock >= 50 THEN 50 ELSE 0

I would have expected the value of the stock to plunge to zero after it reached or exceeded 50, but this graph shows the resulting odd saw-tooth pattern.

The model ends up behaving like a skipping scratched record, in a perpetual state of never progressing far enough to reach the goal of zero.  (Click here to download the model.)

What is happening in the model?  In the first DT after the stock’s value reaches exactly 50, the outflow sets itself to 50 in order to remove the contents from the stock. So far so good, but now the DT gotcha begins to occur.   Since the outflow works over time, its value is always per time.  To get the quantity of material that actually flowed, you must multiply the outflow value (or rate) by how long the material was flowing.  When DT is set to 0.25,  the material flows 0.25 time units each DT.  Hence, the quantity of material removed from the stock is 50*0.25 = 12.50.

Suddenly we are in a situation where only 12.50 has been removed from the stock but the stock’s value is now less than 50.  Since the stock is no longer greater than or equal to 50, the outflow sets itself back to 0 and never actually flushes out the full contents of the stock. 

So what do we do?  One solution to this problem would be to use the PULSE built-in to remove the full value from the stock.   Here’s what the equation for the outflow would look like:

outflow = IF Stock >= 50 THEN PULSE(Stock) ELSE 0

(Note: This option will only work using Euler’s integration method.)

Further Reading

STELLA and iThink have great help documentation on DT.  The general introduction provides a good explanation of how DT works. The more advanced DT Situations Requiring Special Care section focuses more on artifactual delays and the discrete model issues mentioned in this post.  Delta time and resulting model behaviors are reminders that system dynamics models run over time, but they achieve this by applying numerous discrete calculations in order to simulate the smooth behavior of actual systems.

Compound Interest:  Euler’s Method over Runge-Kutta

To introduce Euler’s method, let’s take a look at the simple problem of compound interest.  If we have $100 that we invest at 10% (or 0.1) compounded annually, we can calculate the interest after N years by adding in the interest each year and recalculating:

1st year:  interest = $1000 × 0.1 = $100; Balance = 1000 + 100 = $1100
2nd year: interest = $1100 × 0.1 = $110; Balance = 1100 + 110 = $1210
3rd year:  interest = $1210 × 0.1 = $121; Balance = 1210 + 121 = $1331

And so on up to year N.  We have just seen the essence of how Euler’s method works.  It calculates the new change in the stock for this DT (in this case, interest) and then adds that to the previous value of the stock (Balance) to get the new value of the stock.  In this example, DT = 1 year.

By noticing we always add the existing balance in, we can instead just multiply the previous year’s balance by 1 + rate = 1 + 0.1 = 1.1:

1st year:  Balance = $1000 × 1.1 = $1100
2nd year: Balance = $1100 × 1.1 = $1210
3rd year:  Balance = $1210 × 1.1 = $1331

And so on up to year N. We can further generalize by noticing we are multiplying by 1.1 N times and thus arrive at the compound interest formula:

Balance = Initial_Balance*(1 + rate)^N

Checking this, we find our Balance at the end of year 3 is 1000*1.1^3 = $1331.  In the general case of the formula, rate is the fractional interest rate per compounding period and N is the number of compounding periods (an integer).  In our example, the compounding period is one year, so rate is the annual fractional interest rate and N is the number of years.  However, if interest is compounded quarterly (four times a year), the interest rate has to be adjusted to a per quarter rate by dividing by 4 (so rate = 0.1/4 = 0.025) and N must be expressed as the number of quarters (N = number of years*4 = 3*4 = 12 for the end of year 3).  We can use this formula in our model to test the accuracy of Euler’s method.  Note that for quarterly compounding, we would set DT = 1/4 = 0.25 years.

To explore the differences between Euler’s and Runge-Kutta, the following structure will be used for all of the examples in this post.  This structure models the compound interest problem outlined above.

The equations change for each example and can be seen in the individual model files (accessed by clicking here).  For this example, the actual value is calculated using the compound interest formula, Initial_Balance*(1 + rate)^TIME.  The approximated value is calculated by integrating rate*Approx_Balance (into Approx_Balance).

In addition to the actual and approximate values, three errors are also calculated across the model run:  the maximum absolute error, the maximum relative error, and the root-mean-squared error (RMSE).  The absolute error is:

ABS(Actual_Balance – Approx_Balance)

The relative error is:

absolute_error/ABS(Actual_Balance)

and is usually expressed as a percentage.  The RMSE is found by averaging the values of the absolute error squared, and then taking the square root of that average.

Running this model under Euler’s method leads to the behavior shown in the following graph.  As expected, Euler’s method tracks this function perfectly.  All three errors are essentially zero.

However, changing the integration method to Runge-Kutta 4 (known as RK4) does not give a good approximation (see graph below).  The relative error is 1.6%, the absolute error is $56 and the RMSE is $26, all rather large for RK4.  DT must be reduced a factor of 32, to 1/128, in order to bring the errors below 0.1% (0.001).

Continuous Compounding:  Runge-Kutta over Euler’s Method

Our friend Euler was a busy mathematician.  He is also famous for discovering the formula for continuously compounding interest.  If you increase the frequency of compounding from once a year to once a month to once a day (what most banks do now and called “daily compounding”) to once a second and so on until you are compounding every infinitesimally small instant (which should remind you of the dt from Calculus), the compound interest formula becomes:

Balance = Initial_Balance*e^(rate*time)

where e ≈ 2.718281828 is Euler’s number, rate is the annual fractional interest rate, and time is the number of years that have passed (a real number).  Using continuous compounding, our Balance at the end of year 3 is 1000*e^(0.1*3) ≈ $1350, $8 more than with annual compounding.

This function is known as continuous function, which, in layman’s terms, means its value smoothly changes with time, rather than experiencing jumps or gaps.  [Note the compound interest formula given in the first section is not continuous; since N must be an integer, this function only exists at integer values.]  While Euler’s method does not depend on a function being continuous, it does introduce an error proportional to DT when trying to integrate these equations (called truncation error).  Thus, the only way to reduce these errors is to reduce DT, requiring more computations.  Unfortunately, this only works up to a point.  Below that point, errors increase again due to round-off error in the computer’s finite representation of floating point values.

The graph below shows the effect of using Euler’s method to calculate continuously compounding interest.  Note it does not follow the actual curve, calculated with the EXP function, very well.  The relative error is 1.6%, the maximum error is $56, and the RMSE is $25.  If we cut DT in half, to 1/8, the errors also cut in half as we expect, to 0.8%, $29, and $13, respectively.  This will continue until DT reaches the limit of the machine’s representation, which is approximately 1/2048 for single-precision floating point numbers and 1/67,108,864 (1/2^26) for double-precision floating point numbers (note STELLA and iThink always use double-precision).  After this point, errors will increase again.  Note these values are theoretical; your mileage will vary.

There is a better solution than reducing DT.  The Runge-Kutta integration method assumes a continuous function and takes steps to follow such a function very closely.  Because it uses a weighted average of values across each DT-interval, it does not perform well with discontinuous functions, i.e., functions that have gaps or sharp changes, such as that produced with the STEP and PULSE functions (however, STELLA and iThink compensate for this so that these functions still perform correctly under Runge-Kutta).  Leaving DT at 0.25 and changing the integration method to RK4 produces the following graph, with the largest relative error being 0.0077%, the largest absolute error being $0.27 and the RMSE being $0.14.  To achieve this level of accuracy with Euler’s method, it is necessary to reduce DT to 1/1024.

The number after the RK is the order of the integration method.  Typically, but not always, higher-order methods will give smaller errors.  Euler’s method is a first-order method and RK4 is a fourth-order method.  Note, however, that Euler’s outperformed RK4 in the first example.  STELLA and iThink also provide a second-order method, Runge-Kutta 2 (RK2), which is a compromise between Euler’s and RK4; with the speed of today’s computers, it is no longer necessary to use and remains only for backward-compatibility.

Oscillations:  The Case for Runge-Kutta

Oscillations represent one area where RK4 really shines.  The following graph shows the results of using Euler’s method to integrate the sine function with DT = 0.25.  Notice it misses horribly.  The resulting function is clearly outside the range of the sine function [-1, 1].  The maximum absolute error is 0.25 and the RMSE is 0.15.  However, the maximum relative error is 340%!

Reducing DT by a factor of 128 to 1/512 helps somewhat (below).  The maximum absolute error reduces to 0.0020 and the RMSE to 0.0012, but the maximum relative error only decreases to 200%.

On the other hand, if we leave DT = 0.25 and change the integration method to RK4, it calculates the sine function quite well, with a maximum absolute error of only 0.0078 and an RMSE of 0.0045.  The maximum relative error is also acceptable at 2.2%.  Cutting DT in half to 1/8 reduces the maximum relative error an order of magnitude, to 0.34%.

Guidelines for DT

DT should initially be set to one-half of the smallest time constant in your model.  This minimal value, according to Nyquist’s Sampling Theorem, avoids undersampling your values.  [Undersampling means looking at your signal so infrequently that you distort the signal, or, more to the point, do not have enough information to reconstruct it.  For example, in the sine wave above, evaluating it every π will make you think you have a straight line at the origin, since all you will see are the zeroes.]

Finding the smallest time constant can be tricky.  They often appear in compounding or in draining processes.  For example, in the first two examples, the interest rate is the reciprocal of the time constant (it always appears in the divisor).  Thus, the time constant for this compounding formula is 10.  This suggests DT could start at 5, but there are other constraints.  In fact, we wish to compound every quarter, so DT must be set to 1/4.

Run the model with your chosen DT.  Then cut DT in half and try again.  If the results change, cut DT in half and try again.  If they do not change, the previously chosen DT is likely fine.

Whenever possible, choose a value of DT that is a power of 2 (1, 1/2, 1/4, 1/8, 1/16, … or 1, 0.5, 0.25, 0.125, 0.0625, …).  This is because most other fractions, for example 1/10, are repeating decimals in base-2 and so cannot be accurately represented on the computer.  Obviously if your problem requires you to use a DT of 1/7, in weekly simulations for example, do so, but understand that adding 1/7 seven times will not equal one.  There are also other cases where you might need to use a DT that is not a power of 2.  If your smallest time constant is 1/52, for example, choosing the closest power of 2 to (1/52)/2 = 1/104, which is 1/128, would be disastrous.  Your time constant would then be 1/64 sometimes and 1/32 other times, not at all close to what you need.  Make sure you can represent your smallest time constants as a multiple of whatever DT you choose.

Guidelines for Integration Method

Changing DT is often not sufficient.  Your system may exhibit instabilities or wild oscillations caused by the errors in Euler’s method.  It is therefore also wise to always run the model in Euler’s and then in RK4.  If there is a difference, stick with RK4 and proceed to test DT.

Euler’s method is noticeably faster than RK4 and works fine in many situations.  A system that has linear relationships and uses exponential functions that are not based on Euler’s number will work fine using Euler’s method.  For qualitative results, Euler’s will work well in a broad variety of situations.  Euler’s is also the preferred method when you are using discontinuous or discrete functions (but note the discrete functions in STELLA and iThink are Runge-Kutta-aware and should work reasonably well under RK4).

Any continuous system that is based on exponential functions using Euler’s number as a base, and this includes trigonometric functions, oscillations, and logistic functions, will be better served by RK4.  In these cases, you should generally use this method from the start.

There is one additional type of system you may run into that neither of these methods will solve very well:  stiff systems.  In simple terms, a stiff system is one that has time constants of wildly different magnitudes, for example, 0.005 and 10,000.  The smaller time constant suggests a DT of 0.0025 which is far too small for the part of the system with a time constant of 10,000.  It is best to reframe your problem to avoid these situations when possible.  For example, when simulating such a system, the part of the system with a time constant of 10,000 can often be considered constant over a shorter period of interest.  Over long periods of interest, it is often possible to aggregate the behavior of the part of the system with the shorter time constant, using averages instead of exact values.

Note:  The integration method and DT are both set in the Run Specs, accessible from the Run menu.  Additional information can be found in the chapter on DT in the Technical Documentation.

These additional variables will be also used:

transit_time = TRANSTIME(conveyor)
conveyor_length = transit_time/DT
leakage_fraction = the user-specified leakage fraction

Linear Leakage

The default leakage is linear in behavior.  The total amount that leaks across the length of the conveyor is directly proportional to the inflowing amount.  The leakage fraction is the constant of proportionality.  Thus, the fraction of inflowing material that makes it to the conveyor’s outflow is exactly

1 – leakage_fraction

Given the sample model structure above, to achieve equilibrium, conveyor_outflow must equal outflow.  For this to happen, we need to set the inflow as follows:

inflow = outflow/(1 – leakage_fraction)

The conveyor’s steady-state value is then:

conveyor = transit_time*inflow – (conveyor_length – 1)*leakage*DT/2

where the initial value of leakage is:

leakage = leakage_fraction*inflow

This must be calculated outside the program and entered as a constant into the conveyor as conveyors cannot be given equations (they can, however, be set to a the value of a single converter, but you must be careful how you calculate this to avoid circularity).

Exponential Leakage

Optionally, leakage can be made exponential.  The amount that leaks each DT is proportional to the amount remaining in the conveyor.  In this case, the leakage fraction is the fraction that leaks each unit of time so, for long conveyors, a lot of material can leak away.  Given the transit time, the fraction of inflowing material that makes it to the conveyor’s outflow is approximately

1 – (1 – leakage_fraction)^transit_time

Given the sample model structure above, to achieve equilibrium, conveyor_outflow must equal outflow.  For this to happen, we need to set the inflow as follows:

per_dt_no_leak = 1 – leakage_fraction*DT
inflow = outflow/(per_dt_no_leak^conveyor_length)

For steady-state, the conveyor itself must then be set as follows:

conveyor = (inflow*DT)*(1 – per_dt_no_leak^conveyor_length)/(1 – per_dt_no_leak)

Converting from sectors to modules is not very difficult:

1. Make sure there are no connections or flows between sectors.  Replace any of these with ghosts in the target sector.
2. In a new model, create one module for every sector.
3. Copy and paste the structure from each sector into its corresponding module.
4. Connect the modules:  At this point, the model structure has been rearranged into modules, but none of the modules are connected.  The ghosts that were in the sectors became real entities when they were pasted into the modules.  Go back to identify all of these connections and reconnect them in the module-based model.

Stepping Through a Sample Model

Let’s walk through an example.  A small sector-based model is shown below (and is available by clicking here).

This model violates what I would call good sector etiquette:  there are connectors that run between the sectors.  This is often useful in a small model such as this because it makes the feedback loops visible.  However, in a larger model, this can lead to problems such as crossed connections and difficulty in maintaining the model because sectors cannot be easily moved.

Eliminating Cross-Sector Connections

To convert this sector-based model to modules, it is first necessary to remove these cross-sector connections.  This is done with the ghost tool.  The stock Population needs to be ghosted and placed in the Resources Sector and the stock Natural Resources needs to be ghosted and placed in the Population Sector.  The end result is shown below.

Creating the Modules

We are now ready to create, in a new model, one module for each sector, using the Module tool.  The result is shown below.  Although you could manually draw the connections between these modules, we will let the software create the connections for us.

Each module needs to be associated with its own model file.  This is done by double-clicking on each module and choosing “Create Model…”.  Double-click Population, choose “Create Model…”, and name the model file “Population”.  Repeat for Natural Resources, but name the model file “Natural Resources”.

Pasting Structure into the Modules

It is now a simple matter to paste the structure from each sector into each module.  Using the selection tool in the sector frame, select all of the structure in the Population Sector and copy it by choosing Edit->Copy.  Open the Population module in the new model and paste in the structure by choosing Edit->Paste.  The module contents will appear as shown below.  Note that Natural Resources is no longer a ghost; there is no connection to the other module.

Repeat this process with the Resources Sector and the Natural Resources module.  The module contents will appear as shown below.  Note that Population is no longer a ghost.

Connecting the Modules

All that remains is to connect the modules.  Inside the Population module, the stock Natural Resources needs to be replaced with a ghost of the real stock.  Inside the Natural Resources stock, the Population stock must be replaced with a ghost.

There are two ways to do this:  manually or semi-automatically with the Ghost tool.  I tend to use the Ghost tool most of the time.  [The documentation chapter “Working with Module Inputs and Outputs” (available by clicking here) explains how to forge these connections manually.]

To connect the modules, first go into the Natural Resources module and select the Natural Resources stock with the Ghost tool.  Go up one level and then down into the Population module.  The cursor should still be a stock.  Click next to the existing Natural Resources stock to deposit the ghost.  Run a connector from the ghost to resources\person (as the stock does) and then delete the stock.  Drag the ghost over to approximately where the stock was.  Open resources\person and press “OK”.  An error will appear and “Natural_Resources” will be selected.  This happens because Natural Resources is no longer connected to resources\person.  Click on the ghost’s name (Natural Resources.Natural Resources) in the “Required Inputs” list and press “OK”.  The Population module is now properly connected to the Natural Resources module.

Repeat this process to connect a ghost of the real Population stock to the Natural Resources module.  After finishing, the Population module contents appears as shown below.  Note that Population has a double border to signify it is providing its value to another module.

The contents of the Natural Resources module appears as shown below.  Note the double border around the Natural Resources stock, signifying that it is providing its value to another module.

Finally, returning to the top-level, we see that the software automatically created the required connections between the modules.  Below, the connections have been embellished with their polarity to make the balancing loop obvious.  [The final model is available by clicking here.]

A Cautionary Tale

This mechanical process for converting a sector-based model to a module-based model is very appealing due to its simplicity.  It works very well with models that have a small number of sectors (up to about five), but will fall apart beyond that.

Last summer, I helped Khalid Saeed (Worcestor Polytechnic Institute) convert a sector-based model of Jay Forrester’s Urban Dynamics model to modules.  A direct translation using the above process led to the following top-level diagram:

It should be clear that everything is connected to almost everything else.  There is no way to rearrange this diagram to clear up this mess.  For a short time, I flirted with the idea of module ghosts as a solution, but it does not take too long to see that ghosts cannot solve this problem either (indeed, they make it worse).

Recently, I decided to follow my own advice on module hierarchy (see this post).  I also remembered the famous article “The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information” by G.A. Miller (1956).  It explains that we cannot keep more than five to nine things simultaneously in our heads, depending on the person.  So I may be able to absorb the meaning of a diagram with seven modules, but someone else may only be able to understand one with five modules.  For this reason, we should strive to keep the number of modules in a diagram below seven (which also may help explain why the above method works well for a small number of sectors).

Rearranging the Urban Dynamics model into three levels, I was able to simplify the top-level of the diagram to the following, which shows all of the important high-level feedback loops:

There are also lower-level feedback loops within each of these modules.  The one within workforce is just as complicated:

The model logic rests within these second-level modules.  For example, the module underemployed mobility contains the following logic:

Generalizing the Model

When I showed Steve Peterson (at Lexidyne) my brand switching model, he told me there is a more general version that separates the customer loss fraction from the fraction won by another competitor.  This has been presented in Pharmaceutical Product Strategy by Mark Paich, Corey Peck, and Jason Valant.

In my original formulation, the switching probability matrix was the product of these two variables.  However, in many practical cases, the data available comes from two different places and reflects these two separate components.  The revised model structure is shown below.

Instead of one composite switching probability, this model uses a switching out probability that is distinct from the switching in probability.  The switching out probability is a one-dimensional array that, for each product, contains the fraction of customers lost to rivals every time unit (in our case, month).  A sample for the five brands A, B, C, D, and E appears below.

switching out probability

We can see from this table that Brand B is losing 17% of its customers to rivals each and every month!  Whoever is managing that product had better do something quickly.

The other side of the story has to do with which brand the customers are switching to.  The switching in probability matrix contains, for each brand, the fraction of lost customers that migrate to a rival brand.  Thus, each row of this matrix must add up to one (100% of lost customers).  A sample appears below.

switching in probability

Note the diagonal will always be zero.

We can determine a lot of things from this table.  For example, brand B offers no competition to brand D, brand D is the biggest rival of all the other brands, and brand C is brand D’s biggest rival.

Given these probabilities, we can find the number of customers switching out with the equation:

switching_out_probability[Products]*Customers[Products]

We can then use the exact same formulation as previously for switching to:

switching_out[Products]*switching_in_probability[Products, Products]

and switching in:

ARRAYSUM(switching_to[*, Products])

Note that all customers that switch between two brands also pass through a stock called Customers Switching.  This was Steve Peterson’s idea:  If the equations in the model are correct and all rows of switching in probability add up to one, as they ought to, this stock will always be zero.  If it is ever non-zero, you immediately know there is something wrong with the numbers in switching in probability.  [Note:  Due to truncation errors during the simulation, the stock will not identically equal zero, so it has been globally scaled from –1 to +1 using the Range Specs.]

Expanding the Model

The structure given above models rivalry for existing customers quite well.  However, it does not include flows for new customers entering the market or existing customers leaving the market.  The full structure for acquiring and retaining customers looks like this (and is available by clicking here):

New customers are gained by each brand based on their respective market shares.  Each brand also has a fraction of customers who are lost completely to this market, who perhaps move on to other technology or just stop using that type of product.

The simulation results are shown below for the case where all products start with 100 customers, no new customers are added, and the loss rate is zero.

Switching Based on Market Shares

There is one further variant to customer brand switching that may be useful in some circumstances (it is available by clicking here):

In this version, rather than using a switching in probability, the number of customers gained each unit time is determined by a dynamic overall market share, the one-dimensional array switching in market share.  Whereas the previous model (above) includes a mechanism whereby brand X explicitly gains customers from brand Y, this model bases switching on market share dynamics; if a customer decides to stop using brand X, they might then go searching for a replacement and would be more likely pick the market leader.  Note the switching in market share can be the same as the brand’s overall market share or, as shown, it can reflect the different market shares between new customers (market share) and switching customers (switching in market share).

I am frequently asked which built-in function gives either the running mean or running standard deviation of a model variable.  Unfortunately, there is no such built-in at this time (no, that is not what MEAN() does).

Luckily, however, we can replicate the behavior we desire from built-in functions by creating a reusable module.  I can create a module that calculates a running average and a running standard deviation from any model variable.

When building a reusable module component, it is important to carefully define what the input to the module will be (i.e., what are the parameters to the built-in function) and what the output of the module will be (i.e., what is the result or return value of the built-in function).  In this particular case, the input will be the variable whose running average or running standard deviation we wish to find.  There are two outputs:  the running average and the running standard deviation.  Note we do not have to use both outputs all the time.

Thus, our new module can be used as shown below:

Note the name of the module was chosen to give a meaningful context to the running mean and standard deviation variables, which have fixed names defined inside the reusable module.  As in this example, it is always a good idea to give the module outputs general names that make sense when qualified by a context (the module name).

The reusable module itself was built and tested in iThink, and can also be used in STELLA.  The input parameter was given an equation to allow the model to be completely tested and debugged before being reused.  The model appears below and can be downloaded by clicking here.

Note the input to the module is named value.  After importing the module, this will need to be assigned to the variable in question, Cash in the above example.  This can be done from outside the module by right-clicking on Cash and choosing “Module->Assign to”, or right-clicking on value and choosing “Module->Assign Input to”.  The outputs can be assigned in a similar way, or the Ghost tool can be used.

This method, while relatively easy to understand, does accurately compute the standard deviation when the mean of the running sum of squares is close in magnitude to the running mean squared.  An alternate method that does not suffer this problem was developed by Welford in 1962 and is implemented in the model that can be downloaded by clicking here.

Finally, I am including a simple reusable module that finds the maximum value of a model variable across the entire run of a simulation.  It can be downloaded by clicking here.  It uses a stock to hold the maximum value seen so far, and takes advantage of the fact that uniflows cannot be negative.  It is used the same way as the running mean and standard deviation module, but only has one output called maximum.

For more information about modules, consult the iThink and STELLA help files.  These on-line resources are also available:

Using Modules Webinar

Module FAQs

In the second post of this series, I showed how to selectively pull information from an array in order to route water through a watershed.  In this post, I will use the exact same technique to move customers between different product brands.

Switching Customers between Different Products

Business models often need to model gaining customers from, and losing customers to, competing products in a relatively mature market (what Kim Warren, in his excellent book Strategy Management Dynamics, calls “Type 2 Rivalry”).  These are often driven with statistical models developed through market research.  For this application, we need a matrix describing the probability of switching from product A to product B each time unit.  A sample appears in the table below.

switching probability (units: dimensionless)

To read this table, locate the product the customer is presently using in the left column (say, B).  Read across that row (the second row, in this case) until you find the product the customer is switching to (say, C).  The number in that cell (in this case, 0.05 or 5%) is the probability the customer will switch from the first product to the second (from B to C) in this time unit.  If the model is running in months, as ours is, this table indicates that 5% of customers using product B switch to product C every month.

Of course, the values in the table do not need to be constant.  Often each cell will contain a regression equation based on various product characteristics – including market share, marketing effort, product features, and product quality – that evolve over the course of the simulation.

Note the diagonal is zero.  This means customers do not switch from one product to the same product.

Note also that the sum in any row cannot exceed 1.0, which represents 100% of the customers using that product.  It is quite normal for it to be below 1.0 because we do not include people who are not switching.  Some modelers find it easier to always have each row add up to 1.0.  If you desire to do this, fill the diagonal with the difference between 1.0 and the sum of the other columns.  For example, to do this for product A, replace the top left cell with 1.0 – (0.01 + 0.03 + 0.05 + 0.001) = 0.909 [for you Beatles fans].

Exploring the Model

The model is slightly different from the watershed model in my previous post.  This model is driven by the probability of switching.  Thus, it is driven by the stock of customers for each product, while the watershed model was driven by the outflow from each reach.  This is shown below (and is available by clicking here).

The two-dimensional array switching (called a “switching matrix”) is derived by multiplying customers by the switching probability:

Customers[Products]*switching_probability[Products, Products]

This equation does not perform a traditional matrix multiplication, but multiplies each element of Customers (a one-dimensional column) by every element in the corresponding row of switching probability (two-dimensional).  [For more information about matrix arithmetic in iThink and STELLA, click here.]  As an example, given the switching probability above, if 100 customers use each of products A, B, C, D, and E, the values of switching with its row and column totals would be:

switching (units: customers)

These numbers are derived by multiplying the entire row for each product by 100, the number of customers using that product (again, this example uses 100 customers for each product).  The number of customers switching from a given brand each month is the sum of that product’s row.  The number of customers switching to a given brand each month is the sum of that product’s column.

Thus, 9.1 existing customers switch from (stop using) product A this month while 4.2 customers switch to (start using) product A this month.  Product A will therefore have a net loss of 9.1 – 4.2 = 4.9 customers for the month.

The switching matrix directly drives both the loss of customers and the gain of customers.  The former, losing_customers, sums rows:

ARRAYSUM(switching[Products, *])

while the latter, gaining_customers, sums columns:

ARRAYSUM(switching[*, Products]).

Running the Model

The simulation results are shown below for the case where all products start with 100 customers and no new customers are added.

Note the product with the largest net gain = Total In – Total Out, product D, gains the most market share over the course of the simulation, while that with the smallest net gain, product B, loses the most.

Next time, I will show a more general switching matrix formulation.

This is the second installment of a multipart series.  The first part can be found by clicking here. Part 3 is available here.

In the first post of this series, I showed how to conditionally pull information from an array.  In this post, I will extend this concept to show how to route information through an arrayed model.  This is especially useful in spatial modeling applications.

Routing Water Through a Watershed

A common ecology application is the modeling of a watershed.  Part of such a model will necessarily involve a network of stream or river segments – called reaches – which feed each other.  It is desirable to implement this in a way that makes it easy to modify the reach network.  Using an explicit stock-flow network makes this very difficult.  However, it is relatively straightforward to use arrays of stocks and flows to build an easily configurable network.

Imagine a small watershed broken down into reaches as shown below:

For our purposes, a new reach will need to be created at every junction point.  Therefore, in this example and from a topological point-of-view, it is not strictly necessary to treat reach 4 separately from reach 2 nor reach 5 separately from reach 3, but reaches 2 and 3 must be separate from reach 1.  There are, of course, other reasons to separate reach 4 from 2 and reach 5 from 3, for example, slope, channel width, length, etc.

Every reach flows into exactly one other reach at its head, but many reaches can flow into the head of the same reach.  This requires a many-to-one representation of the reach network.  This is accomplished quite easily with a routing map which, for each reach, contains the number of the reach that this reach flows into.  We also need someway to signify the outlet.  Since reach numbers start at one, we can use zero to signify the outlet.  Using these rules, the above network is completely represented in the following routing map:

The nice thing about this representation is that it fits nicely into a one-dimensional array where the array index is the reach number and the reach it flows into is the value stored in that array element.

The model itself uses one stock to represent each reach.   That stock has one inflow for water entering the reach and one outflow for water leaving the reach: (Download the zipped STELLA model here)

The Routing Magic

The outflow of one reach is directed to the next through the two-dimensional array route water.  This array is arranged with one outflow per row and one inflow per column.  Thus, the outflows are placed one per row in the proper column for the reach it is headed for.  This means there can only be one non-zero value in each row.  For example, at one point in the simulation, the array route water contains these values:

As expected, there is at most one non-zero value for each row.  There is no non-zero value in the first row because that corresponds to the outlet, so no water is routed to another reach.  The value in the second row is the outflow from reach 2, the value in the third is the outflow from reach 3, and so on.  The columns sum to the amount of water being fed to the given reach.  So reach 1 will receive 1.04 + 0.87 = 1.91, reach 2 will receive 0.33, and reach 3 will receive 0.24.  Reaches 4 and 5 receive no inflow because they are at the top of the watershed (there are no reaches feeding into them).

The equation that does this magic is:

IF (routing_map[Reaches] = ARRAYIDX(2))
THEN outflow[Reaches]
ELSE 0

This says that when the column number (ARRAYIDX(2)) equals the reach number of the downstream reach (routing_map[Reaches]), fill the cell with that reach’s outflow.  Note that we at most define one downstream reach for each reach, so this will only be non-zero in only one column.  In this way, we avoid violating conservation of water.

The inflow then needs to sum the columns to get the total flow directed into that reach:

ARRAYSUM(route_water[*,Reaches])

The outflow at the stream outlet is captured in the converter final outflow, which has the equation:

ARRAYVALUE(outflow[*], ARRAYMINIDX(routing_map[*]))

This picks up the outflow value of the reach that has the smallest entry in the routing map.  Since we defined the outlet to have the smallest value, zero, as long as we do not accidentally give two entries a zero value in the routing map, ARRAYMINIDX will find the array index (i.e., reach number) of the outlet.

With constant precipitation, the behavior of the model at the end of a storm event appears below:

Extending the Model

This particular example has two simplifications that are easy to extend.  The average time it takes water to flow through a reach (avg reach length in minutes) is constant, but can be made an array with different values for each reach.  These values can also be calculated as the simulation progresses based on existing conditions in the reach.  There is also a constant precipitation to all reaches all the time to keep water flowing into the system.  This can be replaced by an array and a more intricate model of how precipitation flows into the stream over the landscape, or by a simple time series using a graphical function.

One final note about the model:  I chose a stock with an average residence time to represent each reach.  Under some circumstances, this may generate results that are confusing.  For example, because it is an average residence time that follows an exponential distribution, some water that appears at the top of a reach will immediately exit from the bottom of the reach and other water that enters the reach will exit long after the average time has expired.  In individual circumstances, for example a single short storm event, this representation may not match the real world very well.  However, on average, over a long enough period of time, it matches the real behavior quite closely.

One alternative that enforces an exact delay for water moving across each reach is a conveyor.  However, a conveyor is discrete in its behavior, so the model will not behave as true water flow does, i.e., continuously.  Three stocks, i.e., a third-order material delay, could also be used for each reach to reduce the amount of entering water that exits immediately.  Although this does cause the model to retain more water at the start of an event, it also leads to water being lost more quickly at the end.

Next time, I will use this same structure to model customers switching between different brands.

Using arrays can be quite intimidating for most people. Many times, it is difficult to discover the correct way to formulate a problem in terms of arrays, especially when trying to do so in terms of single equations that can be applied to all elements of the array.

Consider the case where you might wish to count the number of occurrences of a value in an array. This can arise in many applications that need to track attributes, but is prevalent in spatially-explicit business applications. In such an application, you may associate a product code with a location and then want a count of the products of a given type. The following examples demonstrate a common way to extract conditional information from an array.

Finding the Number of Stations with a Given Status

Imagine you have a two-dimensional grid of fire stations in a city, called Stations, that stores one of four statuses:

0: no station in this sector
1: ready
2: away on a call
3: refitting

You consider the number of fire stations ready at any given moment to be an important metric. To calculate this, connect Stations to another two-dimensional array of the same size called ready stations. This will have a one in an array element if the station for that quadrant is ready and a zero otherwise. Its equation is:

IF Stations[Y, X] = 1 THEN 1 ELSE 0 { station ready? }

Note this equations uses dimension names (i.e., Stations[Y, X]) rather than element names (e.g., Stations[1, 2]). This allows you to create just one equation for the entire array (with “Apply to All” turned on), rather than a separate equation for each individual array element (with “Apply to All” turned off). When “Apply to All” is turned on, the equation for each element of the array is automatically generated by substituting that element’s dimensions for the dimension name in the given equation. All of the examples in this post use dimension names.

The total number of ready stations is now just the sum of all of the elements in the array ready stations. This is easily calculated by connecting ready stations to a scalar converter named total ready stations that has the equation

ARRAYSUM(ready_stations[*, *])

The model is shown below and can be downloaded by clicking here.

This general method can be used anytime we need to count the number of elements in an array based on some condition. First, create an array that has its elements set to one if the array-based condition is met and zero otherwise (IF condition THEN 1 ELSE 0). Then create a converter to sum the elements of this new array (using ARRAYSUM). Remember to turn “Apply to All” on and use dimension names in the condition rather than element names.

Finding the Number of Stations with Each Status

We can extend this method to map data from an array indexed by one attribute (or dimension), say location, to another array indexed by a different attribute, say status. Imagine now that instead of just counting how many stations are ready, you want to know how many stations have each status.

One way to do this is to extend the structure above to separately count the number of stations in each status, as shown below.

In this case, away stations and refitting stations have the following formulas, respectively:

IF Stations[Y, X] = 2 THEN 1 ELSE 0 { station away? }
IF Stations[Y, X] = 3 THEN 1 ELSE 0 { station refitting? }

Walking Through a Specific Example

Let’s look at what happens in this model if array of fire stations is only one-dimensional, Stations[Location], and each location is named. This eliminates the “no station in this sector” status. Consider a five-location fire department with the following statuses in each location, held in the array Stations:

The structure above would generate the following values in the three separate arrays ready stations, away stations, and refitting stations. Their respective sums, in the three corresponding “total status stations” converters, are shown at the bottom.

While this method works, it does not have a very flexible structure. It requires structural changes whenever a new status is added (or removed) and also needs to be customized for every individual application. There are also applications (for example, tracking products) where it is necessary to move between arrays that are indexed by location, as Stations is, and arrays that are indexed by the data within the location, in this case by status.

A More General Solution

If we define another array dimension called Status, with element names Ready, Away, and Refitting that correspond to the numeric statuses 1, 2, and 3, we can represent this same solution in one two-dimensional array station map[Location, Status]:

The array station map allows us to map stations directly to their statuses. Each row of the map represents one station. By definition, there can only be one “1″ in each row because a station can only have one status. The sum of each row is the number of statuses that are assigned to that station, which must always be one. Each column of the map represents one status. Multiple “1″s can appear in the columns because many stations can have the same status. The sum of each column is the number of stations assigned to that status, the value we are trying to determine.

Note the similarity between this two-dimensional array and the preceding table that shows the contents of the individual one-dimensional arrays ready stations, away stations, and refitting stations. Each column of station map corresponds to one of these one-dimensional arrays.

The model for this more general solution is shown below and can be downloaded by clicking here.

The equation for station map[Location, Status], which will map Stations as illustrated above, is

IF Stations[Location] = ARRAYIDX(2) THEN 1 ELSE 0

Note the use of ARRAYIDX() to parameterize the status we are interested in for this array element. The parameter to ARRAYIDX, 2, gives the index of the second dimension for this array element, i.e., the index that corresponds to Status. Since Apply to All is on, this will become the desired status for each array element.

The number of stations with each status is calculated in the one-dimensional converter station totals[Status] using the equation

ARRAYSUM(station_map[*, Status])

This equation sums the columns of station map. For the above example, station totals will be filled with the values 3 (Ready), 1 (Away), and 1 (Refitting). Note we have used an intermediate two-dimensional array, station map, to properly map our data from a one-dimensional array indexed by the attribute Location to another one-dimensional array indexed by the attribute Status.

Next time, I will expand this concept to create general routing structures.

• Navigation buttons are styled to look like hyperlinks instead of push buttons.
• Push buttons are used to perform actions, such as running the simulation.
• Tabs along the top of each page let the viewer know which section they are in, as well as providing a way to quickly jump to any section.

An example of the interface template applied to a model published online

You can download the template model and use it as a starting point for creating interfaces to models you want to publish online.

Download the template for STELLA

Download the template for iThink

How to use the template

The template model consists of four interface pages: Home, Background, Explore Model and Simulate.  Navigation buttons to and from each page are already setup within the interface.  You can customize each section by replacing the placeholder text.  The pages are a starting point that establishes a website-like look and feel.

The easiest way to apply the template model’s interface to your own model is to simply copy and paste the pages.

1. Open your own model and switch to the Interface layer.  Choose ‘Interface Prefs’ from the Interface menu and make sure the ‘Show Pages’ option is selected.  Set Page Size to 800×600.  This will allow you to see the page boundaries as you apply the template.
2. Open the template model and from the Interface layer choose the Edit menu –> Select All, then Edit menu –> Copy to copy all of the pages to the clipboard.
3. Go back to the interface layer of your model and choose Edit menu –> Paste.

When you have pasted the pages into your model, they will probably not be lined up correctly within the page boundaries.  The dashed lines show the boundaries of each page.  Using these dashed lines as a guide, use the arrow keys on your keyboard to make the pasted pages line up properly.

Now you can customize the title and text in each page.  Add a picture to the home page and build a control panel.  If you want, you can use the hyperlink button on the ‘Background’ page to link to online information, (PDFs, other models, Wikipedia, etc.).  Consider building a storytelling sequence on the ‘Explore Model’ page to unfurl the model a chunk at a time.  These are just a few customizations you can make.  Take a look at some of our sample models published online with isee NetSim for ideas.

If you publish some models online that use the template, we’d love to see them!  Leave a link in the comments so we can check them out!

• Addition and Subtraction
• Transposition
• Extracting the Diagonal of a Square Matrix
• Multiplying and Dividing by a Scalar
• Multiplying a Square Matrix by a Vector
• Multiplying a Non-Square Matrix by a Vector
• Multiplying Two Matrices

In the examples provided, I use five different arrays of varying dimensions. They are all defined using the subscript name Dim3, which is size 3.

a: 3×3
b: 3×3
c: 3×3
d: 3×1 [one-dimensional]
e: 3×1 [one-dimensional]

I also use two arrays based on Dim3, as well as the subscript name Dim2, which is size 2.

s: 2×3
t: 3×2

Addition and Subtraction

The easiest functions to perform are addition and subtraction. When two arrays have the same dimensions, they can be added and subtracted in the usual way, placing the result in a third array of the same dimensions.

For example, to place the difference of b and c into array a, set the equation of a to

b[Dim3, Dim3] – c[Dim3, Dim3]

Transposition

Transposition of a 2-dimensional array is also relatively easy, especially when the dimensions differ. Suppose we wish to transpose s and place the result in t. Simply set the equation for t to

s[Dim2, Dim3]

This will properly fill t, which has dimensions Dim3xDim2, with:

s₁₁   s₂₁
s₁₂   s₂₂
s₁₃   s₂₃

However, if the two dimensions of the array have the same name, the ARRAYVALUE built-in must be used. Suppose we wish to transpose b, placing its transposition in a. Set the equation of a to

ARRAYVALUE(b[*, *], ARRAYIDX(2), ARRAYIDX())

Note the index of a’s second dimension is used as the index for b’s first dimension and the index of a’s first dimension is used as the index for b’s second dimension.

Extracting the Diagonal of a Square Matrix

Extracting the diagonal from a 2-dimensional array is also very easy. To place the diagonal of a into d, set the equation of d to

a[Dim3, Dim3]

Multiplying and Dividing by a Scalar

Multiplying or dividing by a scalar works as expected. The contents of b can be multiplied by a scalar x, for example, by setting the equation of a to

x*b[Dim3, Dim3]

Multiplying a Square Matrix by a Vector

Matrix multiplication, as defined in linear algebra, is not directly supported at present. It is possible to multiply two arrays, but the results will not match matrix multiplication. When you multiply a 1-dimensional array by a 2-dimensional array, the size of the 1-dimensional array must match either the number of rows or the number of columns in the 2-dimensional array. In both cases, iThink and STELLA treats the 1-dimensional array as either a column or row of scalars that are multiplied across each corresponding row or column, respectively, of the 2-dimensional array.

Given the following equation in a,

d[Dim3]*b[Dim3, Dim3]

d will be treated as a column of scalars (when the 2-dimensional array is square with the same dimension name in both directions, the 1-dimensional array is always treated as a column vector). Each scalar in d will be multiplied across each corresponding row of b. Note this equation does not represent a valid matrix multiplication, and also that switching the order to b[Dim3, Dim3]*d[Dim3], while now a valid matrix multiplication, will not change the result. I recommend leaving the order as above to emphasize that it is not a normal matrix multiplication.

More precisely, the array a will be populated with these values:

d₁*b₁₁   d₁*b₁₂   d₁*b₁₃
d₂*b₂₁   d₂*b₂₂   d₂*b₂₃
d₃*b₃₁   d₃*b₃₂   d₃*b₃₃

Note that these are not the correct terms for matrix multiplication. If we multiply b[Dim3, Dim3]*d[Dim3], which is the only correct way to express it, the linear algebra result is a one-dimensional vector with these values:

d₁*b₁₁ + d₂*b₁₂ + d₃*b₁₃
d₁*b₂₁ + d₂*b₂₂ + d₃*b₂₃
d₁*b₃₁ + d₂*b₃₂ + d₃*b₃₃

If we desire to generate these terms, we must first transpose b by placing the transposition equation given above in c:

ARRAYVALUE(b[*, *], ARRAYIDX(2), ARRAYIDX())

This puts the following values in c, i.e., b transposed:

b₁₁   b₂₁   b₃₁
b₁₂   b₂₂   b₃₂
b₁₃   b₂₃   b₃₃

The equation for a can now be set to

d[Dim3]*c[Dim3, Dim3]

This equation will populate a with these values:

d₁*b₁₁   d₁*b₂₁   d₁*b₃₁
d₂*b₁₂   d₂*b₂₂   d₂*b₃₂
d₃*b₁₃   d₃*b₂₃    d₃*b₃₃

Note that this gives the proper terms for the matrix multiplication, arranged vertically. The final answer is found by summing each column, using the following equation in vector e:

ARRAYSUM(a[*, Dim3])

Aside: The terms we get from the original equation for a, d[Dim3]*b[Dim3, Dim3], are the correct terms for d^Tb, i.e., d-transposed times b, again arranged vertically. If this was the desired result, we do not need to first transpose b and can just sum the columns into vector e as shown above.

Multiplying a Non-Square Matrix by a Vector

If the matrices do not use the same dimension name for both dimensions (square or not), you have much more control over the resultant terms and do not have to resort to transposition at all. The following discussion uses the following additional arrays:

f: 2×3
g: 2×1 [one-dimensional]
s: 2×3t: 3×2

If we multiply f times d, we will get a different result based on whether the resultant array is 2×3 or 3×2. Placing the equation d[Dim3]*f [Dim2, Dim3] into array s yields exactly the terms needed for a matrix multiplication, arranged horizontally:

d₁*f₁₁   d₂*f₁₂   d₃*f₁₃
d₁*f₂₁   d₂*f₂₂   d₃*f₂₃

Setting the equation of g to

ARRAYSUM(s[Dim2, *])

will properly sum the rows into g, giving the result of the matrix multiplication f *d.

If, instead, we place the same equation d[Dim3]*f [Dim2, Dim3] into array t, we get these terms instead:

d₁*f₁₁   d₁*f₂₁
d₂*f₁₂   d₂*f₂₂
d₃*f₁₃   d₃*f₂₃

The correct terms are still available, only now they are arranged vertically and the columns must be summed to arrive at the proper result:

ARRAYSUM(t[*, Dim2])

Multiplying by g instead, i.e., placing the equation g[Dim2]*f [Dim2, Dim3] into s, yields these terms:

g₁*f₁₁   g₁*f₁₂   g₁*f₁₃
g₂*f₂₁   g₂*f₂₂   g₂*f₂₃

These are the terms for g^Tf , arranged vertically. Placing the equation into t gives the same terms horizontally. To calculate f ^Tg, it is necessary to first transpose f by setting t to the equation

f [Dim2, Dim3]

When this is multiplied by g, the correct terms for f ^Tg will be generated (horizontally in a 3×2 array and vertically in a 2×3 array).

Multiplying Two Matrices

Unfortunately, there is no way to easily generate the terms for multiplying two matrices. The equations must be individually tailored for each case. As an example, let’s look at multiplying t*s and storing the result in a. Array t is 3×2 and array s is 2×3, so the result will fit in a (3×3). The correct answer is:

t₁₁*s₁₁ + t₁₂*s₂₁    t₁₁*s₁₂ + t₁₂*s₂₂    t₁₁*s₁₃ + t₁₂*s₂₃
t₂₁*s₁₁ + t₂₂*s₂₁    t₂₁*s₁₂ + t₂₂*s₂₂    t₂₁*s₁₃ + t₂₂*s₂₃
t₃₁*s₁₁ + t₃₂*s₂₁    t₃₁*s₁₂ + t₃₂*s₂₂    t₃₁*s₁₃ + t₃₂*s₂₃

Examining these values for a pattern that could be used in an apply-to-all equation, we can see the proper equation for array a is

t[Dim3, 1]*s[1, Dim3] + t[Dim3, 2]*s[2, Dim3]

This pattern, incidentally, will hold in general for any two matrices. However, this equation does not work as an apply-to-all equation because the same name is used for both the first and second dimensions so it is not possible to tell which of the two varying Dim3 values to use. In this case, iThink and STELLA currently always substitutes the value of the first dimension, which will not give the correct answer. This will always be a problem when the resulting array is square. One workaround is to define an additional dimension name that is the same size as Dim3. This works, but may lead to other array incompatibilities. The other solution is similar to how we transposed a square matrix – explicitly use ARRAYVALUE for any references to the second dimension:

t[Dim3, 1]*ARRAYVALUE(s[*, *], 1, ARRAYIDX(2))
+ t[Dim3, 2]*ARRAYVALUE(s[*, *], 2, ARRAYIDX(2))

This is certainly not as clear, but it works and is only necessary when the result is square. One last example underscores this point and also shows how to expand the general pattern to a larger array. For this example, one more dimension name, Dim4, of size 4 and two more arrays are needed:

u: 3×4
v: 2×4

To calculate the result of s*u in array v, where s is 2×3, u is 3×4, and v is (correctly) 2×4, set the equation for v to:

s[Dim2, 1]*u[1, Dim4] + s[Dim2, 2]*u[2, Dim4] + s[Dim2, 3]*u[3, Dim4]

Note this same method can be used for multiplying a 2-dimensional array by a 1-dimensional array instead of the method presented above. It avoids both the intermediate transposition and product arrays, but results in more complex expressions that must be tailored to each combination of array sizes.

Since a lot of customers are now getting their feet wet with modules, we’ve been receiving a steady stream of questions.  We asked our Director of Product Development Karim Chichakly to compile a list of frequently asked questions that he thought would be useful for anyone using modules.  The questions and answers are listed below. If you have any additional questions, post them in the comments and we’ll respond.

What is a module?

A module is a container for lower-level model structure.  It is designed to support a process of top-down model design and development.

What is a module input?

A module input is a variable that can become the ghost of another variable at a different level of the module hierarchy.   It becomes the ghost when you assign it to that other variable.  After it is assigned, it is referred to both as a cross-level ghost and an assigned module input.  All of this is managed transparently if you use the ghost tool.

What is a module output?

When a variable is designated as a module output, you are telling the software that this variable can be ghosted on a different level of the module hierarchy.  While any variable can be a module output, it is important to carefully manage which variables you intend to be shared across modules.

How are modules different from Decision Process Diamonds (DPDs)?

DPDs were designed to collapse one level of structure and hide non-essential details while modules were designed for top-down development of complex models.  Their goals are very different and so is their behavior.  While it is true that modules can be used to replace DPDs, the reverse is not true.

Why can’t I directly connect modules to variables as I can with DPDs?

Although it may appear that they are, DPDs are never directly connected to anything.  When a DPD is connected to a variable, a “nub” (which is just a placeholder) is placed inside the DPD.  In order to get the model to work, you must open the DPD and connect that nub to a variable in the DPD.  When you do this, you have connected a variable that is hidden inside the DPD directly to a variable outside the DPD – and this connection is visible while the DPD is extant.

We chose a different metaphor for modules because modules do not appear side-by-side with the model they are in.  Thus, you cannot see the connections.  Although we could have created nubs like in the DPD, we would have had to give the nubs names which then persisted on connections going out to the diagram frame after the variable was connected.  Again, it is important to remember that DPDs are not connected to variables any more than modules are – variables are connected one-to-one with other variables.

What is the metaphor for modules?

For modules, we decided the proper metaphor was that of ghosts, which are already used to refer to a variable elsewhere in a model.  In fact, the most natural (and easiest) method to connect variables in different modules is with the ghost tool.

As a result, all variables used from another module are clearly visible within the module that uses them.  The use of those variables inside the module is also clearly visible.

A direct consequence of this metaphor is that no connections can be made across levels without first going through a cross-level ghost (also known as a module input).  This is different from the requirements of a DPD, which allowed you to see the variable inside the DPD at the same time as the variable outside the DPD.

How are modules different from submodels?

Like DPDs, submodels collapse one level of structure.  They were specifically designed to hide low-level details of processes from the top-level of the model.  A submodel is a proxy for a stock and, in this way, varies dramatically from a module which presently has no value at all.  Also, a submodel allows several outflows from a process to be rolled up (summed) into one outflow of the submodel, which modules do not allow (there are not flows into or out of modules).  However, modules do allow a main chain to cross their boundaries in much the same way a submodel does.

How are modules different from sectors?

Sectors and modules represent the same basic concept:  A fundamental unit of the model at a high-level with detail inside.  The difference is the sector does not hide that detail within it and cannot be nested.  The module hides the detail within it and can be nested as many levels as desired.  Sectors can still be useful for breaking up small models.

Will all four methods of organizing model structure continue to exist in the future?

While there remain clear and separate uses for sectors and modules, the functionality of the DPD almost completely overlaps that of the module.  The submodel, which is used infrequently nowadays, also mostly overlaps with the module.  At some point in the future, both the DPD and the submodel will be removed from the software.

Why can’t I connect a module to a module output?

Whatever variable a module gets connected to must be able to become a cross-level ghost.  This means it cannot have any connections into it and it cannot be a module output, as no variable can be both a module input and a module output.  To use a variable in a module, you must first ghost it in the current module.

Why can’t a variable be both a module input and module output?

Because a module input is the ghost of another variable.  A ghost just represents the variable – it is not the variable itself.  Connections should be made from the original variable whenever possible.  When this is not possible, an intermediate variable set identically equal to the original variable can be used.

Why does the software complain that I cannot connect a module to a module output when I didn’t create a module output (and there is no indication on the variable concerned)?

There are two types of module outputs:  explicit and implicit.  An explicit module output is created by right-clicking on the variable and choosing Module->Provide Output from the context menu.  After doing this, there will be a second border drawn inside the variable (that looks like a large O in converters and flows) and that variable will be accessible in the module directly above this one and in all modules (and their submodules) connected to this one.  Note the ghost tool also creates explicit module outputs.

An implicit module output is created any time a variable is connected to a module.  This variable is treated as a parameter to that module and that module alone, so can only be accessed inside that module.  The only visual indication that this is a module output is the connecter running from the variable to the module.  There is no mark on the variable and the context menu will not claim it is a module output.  This is because the context menu is for setting explicit module outputs which behave slightly differently.

Can the file hierarchy for modules match the model hierarchy?

At present, all modules must exist at the same level in the Modules folder.  This does mean that all filenames must be unique.

Can the modules be saved in one file with the top-level model?

At present, all modules must exist as separate files in the Modules folder.

Can I control import and export independently at each level of the module hierarchy?

At present, import and export sheets can be associated only with the top-level model and should be in the Data folder.  Multiple sheets are allowed, so they can be organized by module.  To import a module variable, make sure to precede the name in the import sheet with the name of the module and a period.  For example, to import variable “x” in module “mod”, the name in the import sheet must be “mod.x”.

Can I put my import and export sheets in the same directory as my modules?

Import and export sheets must appear either within the same directory as the model or in the Data folder, which is itself in the same directory as the model.

If two modules have the same logic, can I share the same module file?

Yes.  However, you will be unable to edit the module while it is assigned to more than one module.  This is indicated by a disabled toolbar and a lock in the upper-left hand corner of the screen.  To edit the module, temporarily disconnect it from all modules but one, edit it, and then reconnect it.  Alternatively, you can open the ITT file directly, edit it, and then re-import it into your model.

The list ranges from Paintbrush tips to keyboard shortcuts. If there are other tricks that you know about, please post a comment and share them with the rest of us!

Bending a flow

Flows

•  Bend a Flow — Drop a Flow and start dragging it. When you want it to change direction at a 90 degree angle, hold the shift key while you move the cursor in the direction you want the Flow to go.

• Change the Flow direction — Hold the Control key and click on the head of the arrow.

• Disconnect a Flow — Click and hold on the end of the Flow (either the arrow end or the tail end) to drag it from a Stock.

Paintbrush

Floating Paintbrush palette

• Move Color Palette — Click on the Paintbrush tool and hold while moving cursor until it moves the whole palette. Drag it anywhere on the window.

• Eyedropper Tool — If you want to duplicate the color of an object but you are not sure which shade you used, you can use the Eyedropper to “extract” the color and reuse it. To identify the color of an entity, select the Paintbrush; do a Control-shift (Windows) or Command-shift (Mac) , and the Eyedropper will appear. Click on the entity and the Paintbrush will take on the color of that entity. Now you can color your model as before.

Toolbar

Tool Menu

• Tool drop down list — Click on a tool and hold to get drop down menu of related choices.

• Activating the last tool — If you have just added an object to your model such as a Stock, and you want to add another, press and hold the Alt key(Windows) or Option key (Macintosh) and click on the model layer to drop additional Stocks. You can use the Alt key to go to back to the last tool you used.

• Sticky tool — Double-click on an object in the toolbar to make it “sticky”.  In this mode the software will not switch back to the arrow after you have dropped the object on the page.  You can keep adding more of the same objects until you hit the Esc key or click on another tool.

• Change default color of a tool — Select a color from the Paintbrush palette, then hold the Alt key (Windows) or Option key (Macintosh) and click on the item in the toolbar.

Graphs & Tables

Variable precision

• Change precision for a graphed variable — Right-click, (Control-click on Macintosh) on the name of the variable in the graph or table.  Select Precision from the menu and choose from the available options.

• Delete pages — Click on the Dynamite tool in the toolbar and drag it to the dog ear on the lower left corner of the graph or table. Click again to delete the current page.

• Clear data — Click on the Dynamite icon on the graph or table itself to clear the data.

• Color variables — Click on the Paintbrush and select a color. Click on the variable name in the graph or table to change the color.

Keyboard Shortcuts

Here is a table of menu shortcuts. It is organized by software layer. I also added some navigation and miscellaneous shortcuts.

Table of keyboard shortcuts (PDF file)

Miscellaneous

Calculator w/ Alt or Option key pressed

• Changing input keys on the Calculator — To change the available input keys on the Calculator, press the Alt key (Windows) or Option key (Mac).

• Navigating out of a Module while building a story — If the story you are building takes you into a Module, you can back out of the Module by holding the Control key (Windows) or Option key (Macintosh) and double-clicking on a blank part of the model layer.

• Quitting out of a Runtime model — To exit out of Runtime model, click on Control key and Q (Windows) or Option key and Q (Macintosh).

So let us know if you have more tips, tricks or shortcuts to share by adding a comment to this post!

Because a basic premise of System Dynamics is that structure and behavior are linked, one of the key ideas behind storytelling is to allow the behavioral story to grow as the structural story unfurls. To create this effect, we neutralize structure that is not showing. This is extremely powerful because it allows you, for example, to selectively show the behavior of different loops within the system.

A simple example will solidify this concept. Consider the following simple population model:

The death rate multiplier is a simple resource constraint on the growth of population. More complex constraints would also affect the birth rate.

This model can be sequenced into a very meaningful structure/behavior story. The storyboard with the corresponding graph of Population for each story panel is:

death rate multiplier = Population/INIT(Population)

Note how the behavior of the model changes as more of the structure becomes extant, and especially as more loops are closed. This is something that cannot be done with, for example, Run by Modules or Run by Sectors.

How Run by Modules/Sectors Operates

These latter two run options work identically. When you run a set of modules (or sectors), inputs from modules that are not running are held at their initial values. Flows across the boundary act as if there is a cloud at whichever end is not in the running module. If sectors are placed around the different pieces of structure in this story and Run by Sectors is used, the behavior is identical (the second to last graph) for all steps but the last.

How Running Under Storytelling Operates

In storytelling, entities that are not visible are essentially removed from the model. The program neutralizes them by setting them to either zero or one based on how they are used in each visible entity’s equation. If there is a either a “+” or a “-” in the visible entity’s equation, the invisible entity will evaluate to zero in that equation. Otherwise, it will evaluate to one in that equation. You can override this default behavior for each entity in the storytelling dialog. In addition, flows that have none of their inputs shown can also be set to default values by hovering over them and typing in a value. This is how births and deaths were set in the first two panels of the story.

Let’s look at a few simple examples to get the feel of it. Let a = 5, b = 7, and c = 2.

The story panels below show the values of x under these scenarios of visible and invisible entities.

x = a + b:

The equation is additive, therefore entities not shown are set equal to 0

Visible Entities
Values	a = 0, b = 0	a = 5, b = 0	a = 0, b = 7	a = 5, b = 7
x	0 + 0 = 0	5 + 0 = 5	0 + 7 = 7	5 + 7 = 12

x = a*b:

The equation is multiplicative, therefore entities not shown are set equal to 1

Visible Entities
Values	a = 1, b = 1	a = 5, b = 1	a = 1, b = 7	a = 5, b = 7
x	1*1 = 1	5*1 = 5	1*7 = 7	5*7 = 35

x = (a + b)*c:

The equation is treated as additive because it has a + symbol, therefore entities not shown are set equal to 0

Visible Entities
Values	a = 0, b = 0, c = 0	a = 5, b = 0, c = 0	a = 0, b = 7, c = 0	a = 0, b = 0, c = 2
x	(0 + 0)*0 = 0	(5 + 0)*0 = 0	(0 + 7)*0 = 0	(0 + 0)*2 = 0

Visible Entities
Values	a = 5, b = 7, c = 0	a = 5, b = 0, c = 2	a = 0, b = 7, c = 2	a = 5, b = 7, c = 2
x	(5 + 7)*0 = 0	(5 + 0)*2 = 10	(0 + 7)*2 = 14	(5 + 7)*2 = 24

The value of the invisible variables is zero in the first and last cases, and one in the middle case. The last case is treated as additive by default because there is a plus sign. This may or may not give the result desired.

It is possible to override the default behavior in the storytelling dialog (by selecting the entity and using the “+ -> *” button at the bottom), though this may not be desired depending on the application. However, to ensure the desired result by default, separate such expressions into their additive and multiplicative components. In this case, add a converter d = a + b and make x = d*c. In this way, x will only be zero when both a and b are invisible.

The following story panels show the values of x under these scenarios of visible and invisible entities.

x = (a + b)*c overridden to be multiplicative:

The default additive behavior is overridden to be multiplicative in this case and therefore the entities not shown are set equal to 1

Visible Entities
Values	a = 1, b = 1, c = 1	a = 5, b = 1, c = 1	a = 1, b = 7, c = 1	a = 1, b = 1, c = 2
x	(1 + 1)*1 = 1	(5 + 1)*1 = 6	(1 + 7)*1 = 8	(1 + 1)*2 = 4

Visible Entities
Values	a = 5, b = 7, c = 1	a = 5, b = 1, c = 2	a = 1, b = 7, c = 2	a = 5, b = 7, c = 2
x	(5 + 7)*1 = 12	(5 + 1)*2 = 12	(1 + 7)*2 = 16	(5 + 7)*2 = 24

x = d*c, where d = a + b:

The equation behavior for x is multiplicative and for d it is additive. Entities that are not shown and inputs to x will be set equal to 1. Entities that are not shown and inputs to d will be set equal to 0.

Visible Entities
Values	d = 1, c = 1	d = 1, c = 2	a = 5, b = 0, c = 1	a = 0, b = 7, c = 1	d = 1, c = 2
x	1*1 = 1	1*2 = 2	(5 + 0)*1 = 5	(0 + 7)*1 = 7	1*2 = 2
Note	a and b are not evaluated	a and b are not evaluated			a and b are not evaluated

Visible Entities
Values	d = 0, c = 1	a = 5, b = 7, c = 1	a = 5, b = 0, c = 2	a = 0, b = 7, c = 2	a = 5, b = 7, c = 2
x	0*1 = 0	(5 + 7)*1 = 12	(5 + 0)*2 = 10	(0 + 7)*2 = 14	(5 + 7)*2 = 24
Note	a and b are not evaluated

Behavior of Ghosts Under Storytelling

Finally, ghosts behave the same, irrespective of whether their parent is visible. This means all the above rules apply, which can sometimes be confusing. For example, if a stock called Population initialized to the constant 100, the story below does what is expected: the ghost of Population will equal 100.

However, in the story below, the behavior is not very likely to be what is expected. If death rate is a constant, there will be no surprises. However, if death rate depends on other variables, as in the example at the beginning of this post, you may be very surprised by the results. In that case, death rate was determined by multiplying two other variables, so it will evaluate to one in this story. To make it evaluate to a more meaningful value, you must also include some of its inputs in this story panel (as was done in that story). This is true, by the way, whether death rate is a ghost or not.

The simulation rules for storytelling can sometimes lead to confusing results, especially in larger models. Hopefully, this post clears up much of the confusion and allows you to build more effective behavioral stories.

Last time, we explored a two dimensional diffusion problem by looking at a metal plate with constant heat applied to the center. The model is available here: 2d-diffusion. The results, using isee Spatial Map, of the start (left) and end (right) of a six-minute simulation are shown below.

I am frequently asked how to set up Spatial Map. isee Spatial Map is a simple program that can be used to display any dataset as a two dimensional grid with specific colors assigned to data ranges. Since it is stand-alone, iThink and STELLA communicate with it through the Export Data functionality. If you wish to plot simulation results in Spatial Map, you must first set up a persistent link to a CSV file. This persistent link is always going to be from a table that contains just one element of the array you wish to view in Spatial Map.

In this example, a table named “Temp Export Table” was created to export the temperature data. The first element, temperature[1, 1], was placed in the table. There is a subtlety here that cannot be overlooked. I wish to plot the values of the stock T as it varies over time. Yet I export a different variable named “temperature”. Why is this?

This is necessary because although stocks can be exported in the format Spatial Map expects, the export settings that are compatible with Spatial Map only export their initial values no matter where the simulation is. If we export T, we will only ever see the initial conditions in Spatial Map. Thus, when displaying a stock in Spatial Map, and we almost always do display stocks, it is necessary to create a converter that is set identically equal to the stock. The converter will export its current values, and since it is equal to the stock, the stock’s current values will be exported. The converter used for this purpose in this sample model is named “temperature”.

Next it is necessary to set up the persistent link. Choose Export Data… from the Edit menu. The Export Type should already be set to Persistent and Dynamic. Under Export Data Source, select “Export variables in table” and choose the table with the array element in it from the pop-up menu. In this case, that table is called “Temp Export Table”. Also select “One set of values” under Interval. This forces the data to be export in the format required by Spatial Map. These settings are shown below.

To finish setting up the export, choose the CSV file to export to and press OK. For this model, the file is named “2D Diffusion.csv”. Note that all of this has already been set up in the attached sample, so you will not be able to set it up again. You can examine the settings, though, by choosing Manage Persistent Links in the Edit menu and then pressing the Edit link at the end of the “Temp Export Data” line in the Export block.

The value of “temperature” will now be exported once at the start of each run and once at the end. If you wish to see the simulation unfold in Spatial Map, it will be necessary to set a Pause interval, as dynamic links are also exported every time the simulation pauses. Under Runs Specs… in the Run menu, you can see that I have set the Pause Interval to 20. This forces the Spatial Map to update every 20 seconds during the simulation run. This also forces the user to keep pressing Run to advance the simulation.

Finally, it is necessary to set up Spatial Map. Launch isee Spatial Map from the iThink or STELLA installation [in the Start menu on Windows, or in the iThink/STELLA folder in Application on the Macintosh]. Press the “Set CSV” button and choose the CSV file that is the target of the export. For this example, the file is named “2D Diffusion.csv”. An empty grid with the same dimensions as the exported array should appear. In this case, the temperature array is 10 by 10. Press the Settings button in the upper left corner. Its icon is three intermeshed gears. This dialog is where most of the magic of Spatial Map occurs. Please refer to Part 3 of the Technical Documentation (www.iseesystems.com/Help) for a full description of how to use this dialog.

At this point, it is important to take a moment to plan what you hope to see. The temperature values on this plate vary from 0 to 100 degrees. It would be ideal if the temperature on the plate was displayed white at zero degrees, red at 100 degrees, and a graduated blend from white to red for values in-between.

Spatial Map allows colors to be assigned to ranges of variables. Blends have been added on top of this interface, making the setting up of blends a little tricky.

The left side of the Settings dialog shows the colors assigned to the various ranges. This will be blank when you first open the dialog. To see an example, double-click the sample named “Test Configuration” on the right side. At this point, three numbers will appear on the left side with colors directly across from each value:

Each value corresponds to the starting value in a range. The previous range ends just below the value given as the start for the next range. For the above setup, if 0 = value < 10, the cell will be colored red. If 10 = value < 20, the cell will be colored blue. If value = 20, the cell will be colored green. Spatial Map always colors values below the lowest value given in white, so if value < 0, the cell will be colored white.

This is fairly straightforward, but does not map directly to blended colors. If values between 0 and 10 are supposed to appear in some shade of red, which value should be full red? 0? 10? 5? If values between 10 and 20 are supposed to appear in some shade of blue, which value should be the full blue that appears here? And what happens at the boundary between red and blue, i.e., at 10? If this is a perfect blend between the two colors, it would seem that values at the boundary (10) should be a 50/50 blend of the two colors red and blue. Based on this fixed point, Spatial Map applies the full color at the middle of the range and blends out to middle of the neighboring ranges. Thus, full red is at 5 and full blue is at 15 with the gradations shown below:

On the other side, the red region blends to an equal-sized white region. Therefore, cell values containing zero will be half white and half red.

This definition of blends also requires that the top color have a fully-defined range so it can be blended with its neighbor and with white beyond that limit. When you select “Blend Colors” at the bottom of the dialog, you are also asked to enter the ending value of the last range. This is really the start of the hidden white range at the top.

For this example, we want to show 0 in white and 100 in red. The simple setup below will not do this.

With blend colors on and the end of the last range set to 150, this setup uses white for all values less than 50 (the middle of the first range), full red at 125 (the middle of the second range), a blend from white to red between 50 and 125 (with half white and half red at 100) and a blend from red to white from 125 to 175 (with half red and half white at 150).

The desired behavior, however, is white at 0, full red at 100, and a blend from white to red in-between. We expect the color to be half white and half red at 50. This gives us three points to use to set up the proper ranges for this blended behavior:

We learned above that the half-blend point is the value we need to use for the start of the range for the second color. Thus, we will place red at 50.

We also learned that the full colors appear at the midpoint of the ranges. Thus, to get white at 0 when the next range boundary is at 50, we must go 50 back from 0 to -50. So we will place white at -50. Finally, we need to define the end of the red range. If 100 is the midpoint of a range that starts at 50, the range will end at 150. This configuration is shown below:

The specific red used in this example is a slightly darkened version of pure red, chosen in order to look more realistic. Click on the color on the right to open the color picker. Start by selecting pure red from the list of basic colors (fourth down in the second column). Tone down the Red (or the Val) component from 255 to 230 in the bottom right (see below) and press OK.

If you have set up Spatial Map correctly, when you run the model, you will see the temperature diffuse across the plate as the simulation progresses, with the spatial map updating each time the model pauses.

Last time, we explored spatial modeling using the one-dimensional diffusion problem as an example.  Many spatial applications, however, require two dimensional formulations.  As an extension, we will now explore the two-dimensional diffusion problem.  Instead of a one-meter metal bar with constant heat applied at its ends, the two-dimensional diffusion problem looks at the response of a one-meter by one-meter metal plate with constant heat applied to its center.  We then watch the heat diffuse across the plate.

At first blush, one might think the two-dimensional case is much more difficult than the one-dimensional case.  In particular, if a grid is superimposed over the plate, each finite element on the plate has eight neighbors, as shown below.  It is tempting, therefore, to consider radiating heat in each of these eight directions.

However, without looking at the two-dimensional diffusion equations, if we consider just the physical layout of this system, the four corners of the finite element only touch the four corner neighbors (1, 3, 5, and 7) at one point.  In contrast, the four sides of the finite element are shared with each of its four immediate neighbors (2, 4, 6, and 8).  This suggests that heat only radiates to (and from) these four neighbors, not all eight.  In fact, if we examine the two-dimensional diffusion equation, we find that there are only component contributions in the x- and the y-directions.  There are no contributions on the diagonal (which would appear in the equation as ∂²u/∂x∂y and ∂²u/∂y∂x terms).

Intuitively, then, we have a finite element that is very similar to the one-dimensional case.  We only need to add corresponding flows in the y-direction.  This leads to the following model with the individual finite elements arrayed.

The array T is now two-dimensional, in x and in y.  In addition, dx can differ from dy, so the diffusion constant C must be broken down into its constituent parts C_x = k/dx² and C_y = k/dy².  This leads to the following set of equations for the radiant flows through the plate:

in left = Cx*T[X - 1, Y]                               in top = Cy*T[X, Y - 1]
out left = Cx*T[X, Y]                                  out top = Cy*T[X, Y]
out right = Cx*T[X, Y]                              out bottom = Cy*T[X, Y]
in right = Cx*T[X + 1, Y]                          in right = Cy*T[X, Y + 1]

X and Y are dimension names for the elements in the x- and ­y-directions, respectively.

Using isee Spatial Map, it is possible to view the results of this diffusion across two dimensions.  Spatial Map displays an array as a one-dimensional or two-dimensional grid (depending on the array).  Each cell in the grid is filled with a color corresponding to the value in the corresponding cell of the array.  Below are two spatial maps.  The one on the left shows the initial conditions of the metal plate.  Note that heat only appears in the center of the plate, where it is being externally applied.  The map on the right shows the distribution of heat across the plate at the end of a six-minute simulation.

The model is available here:  2d-diffusion.  It is already configured to use isee Spatial Map.  In the final installment of this 3-part series, I will describe how to set up isee Spatial Map.

Spatial modeling is concerned with modeling behavior over space as well as time.  Common applications include modeling flows in lakes and streams or modeling development in an urban landscape.  To demonstrate the new capabilities in version 9.1.2, the one-dimensional diffusion problem will be modeled in STELLA.

Consider the diffusion of heat through a one meter metal bar when a constant temperature is applied to both ends.  This problem is typically introduced as the following partial differential equation for temperature function u(x, t) with the given boundary conditions:

∂u/∂t – k ∂²u/∂x² = 0
u(x, 0) = 0, 0 < x < 1
u(0, t) = u₀, t ≥ 0
u(1, t) = u₀, t ≥ 0

Here, k is the diffusion coefficient (based on thermal conductivity, density, and heat capacity) and u₀ is the constant temperature applied to both ends of the bar.  The finite difference solution to this problem (with the above initial conditions) is:

u(x, t + dt) = u(x, t) + ∂u/∂t
∂u/∂t = k (u(x + dx, t) – 2u(x, t) + u(x – dx, t))/dx²

It is also possible to derive a closed-form solution.  Unless you are an astrophysicist, this solution probably does little to help you understand what is happening.  It is far more intuitive to develop a physical model of the underlying mechanics than to wrestle with the mathematics.

If you consider the metal bar as a single object that is being acted on by its environment, it is possible to consider some of the changes to that bar over time.  If the environment is warmer than the bar, there will be an inflow of heat to the bar.  If the bar is warmer than its surrounding environment, there will be an outflow of heat from the bar.  We probably all know from experience that a hot bar will radiate heat outward in all directions, so in a three-dimensional problem, heat would flow outward in all directions.

If you divide the bar into a set of consecutive finite elements (a finite element is just a fancy word for a small fixed-size section of a larger object – finite because its size is bounded), it becomes possible to imagine a model of what happens to each of these elements individually.  Connecting them in tandem should then yield the behavior of the entire bar.  This is the essence of spatial modeling.

Using the ideas above, we must have some amount of heat entering each element and some amount leaving each element.  For this problem, however, which way does the heat radiate?  The problem is intentionally limited to one dimension, x, so the only choice for the direction of radiation (from an element’s point of view) is left or right.  Thus, we can have heat radiating into the element from either the left or right side, and heat radiating out of the element from either the left or right side.  This is shown in the diagram below and is our model for a finite element of the metal bar.  Note that for clarity u has been renamed T for temperature.

If we chain a number of these elements together horizontally, we will have a model of the entire metal bar.  Using three elements leads to the following model of the metal bar.

This model is obviously greatly simplified.  Note that heat applied left is the heat arriving from the left side of T1.  The heat leaving from the left side is zero, so is not even shown.  An analogous simplification has been made to T3.  This simplified model allows us to consider the nature of each of the four flows in our modeled element, as all of them relate to the neighbors of that element.  In this example, T2 has one neighbor to the left, T1, and one neighbor to the right, T3.  Thus, any heat gained from the left must come from T1 and any heat gained from right must come from T3.  In addition, any excess heat T2 has will radiate out to T1 on the left and T3 on the right.  This simple structure allows us to arrive at the equations for the four flows in our finite element model, shown in terms of both this example and the general finite element model:

in left = C·T1 = C·T(x – dx, t)
out left = C·T2 = C·T(x, t)
out right = C·T2 = C·T(x, t)
in right = C·T3 = C·T(x + dx, t)

C is a diffusion constant describing the rate of temperature loss from a warm body, i.e., the fraction radiated by a finite element.  In the one-dimensional case, C = k/dx².  Note that summing these four flows together properly (i.e., adding the inflows and subtracting the outflows) yields the exact same ∂u/∂t equation derived mathematically and shown above.

But are three elements, two of which are held at the applied temperature, sufficient to properly model a one meter metal bar?  Not really.  The number of elements used defines dx.  Specifically, dx = bar length/number of elements, in this case 1 m/3 = 1/3 m.  Like dt, dx must be small enough to properly catch the dynamics of the system.  We need far more elements to properly model this problem.  Since we have broken the metal bar down into identical finite elements, it becomes natural to build the metal bar up using an array of finite elements rather than showing each individual element.  This model looks like this:

Version 9.1.2 allows the equations above to be naturally expressed as Apply to All equations as follows:

in left = C*T[X - 1]
out left = C*T[X]
out right = C*T[X]
in right = C*T[X + 1]

where X is name of the array dimension.  Note the value one is used instead of dx.  This is because each array element represents a finite element of width dx.  The subscript for the array counts elements rather than distance.  To get the position of the element along the bar it is necessary to multiply the index of the element by dx.  Also note that t is not represented by a subscript in the array.  This is because all models already simulate across time.  Therefore, all entities in a model are functions of time.  Running this model gives the expected behavior:

A final note:  Version 9.1.2 allows any constant, not just one, to be added to, or subtracted from, a dimension name in an equation.  The software evaluates T[X + c] to zero when X + c results in a subscript beyond the bounds of the array.  Thus, when X = 1, the first element, T[X - 1] will be forced to zero.  Likewise, when X = DIMSIZE(), the last element, T[X + 1] will be forced to zero.  As you will discover when you explore it, this particular model (1d-diffusion) forces these end conditions to the constant temperature being applied (100 in this case).

Editor’s Note:  This is part 1 of a 3-part series on spatial modeling in iThink and STELLA.  Part 2 is available here.  Part 3 will be posted the week of April 12th, 2009.

I have set up a simple example that illustrates how you could run an iThink model multiple times to skirt the 32,767 time step limit that advanced users sometimes run up against.  The model itself does nothing extraordinary, it simply increments the value of a Stock by one at each time step. What makes it worth noticing is that it runs 32,000 iterations three times to mimic a 96,000 step run.

>> Download the Sample Files

This example will open and run the model file named multiple_run.itm, import data at the beginning of each run, and export data at the end of each run.  You can double-click on the “Start batch runs” shortcut to kick things off or you can use the batch file that is provided. Note that you may have to edit these start files to make them work on your computer

Command Line Syntax

"c:\program files\isee systems\iThink 9.1.2\iThink.exe" -rn 3 multiple_run.itm

The command line above was entered into the “Target” field of the “Start batch runs” Properties dialog.  Note the “Start in” field is intentionally left blank so that the shortcut will run the model from the current directory.  If you move the shortcut file to a different directory,  you’ll need to enter that directory into this field.

The identical command line syntax is used in the supplied batch file named “go.bat” and can be edited using Notepad.

Sample Model and Spreadsheet

The sample model uses a table to report the value of the Stock at the end of each run so that it can be exported to the “multiple_run_data.xls” Excel file. In Excel, I linked the exported value of the Stock to an “Import” worksheet.   This way, one run hands off the final data to start the subsequent run like runners in a relay race passing a baton.  Note the initial Stock value will need to be reset in Excel before starting a new batch of runs.

Running the sample command line puts iThink into a macro mode.  It opens just as if you double-clicked its icon and manually started the runs yourself.   Sit back and watch the model open, and let the model run three times on its own.  Try to leave the process alone while it executes, I did find that if the runs were interrupted the Excel file could sometimes lose its formatting.

For an experiment you could add “-nq” to the command so that the model stays open after running.  After adding the new parameter your command would look like this:

"c:\program files\isee systems\iThink 9.1.2\iThink.exe" -rn 3 -nq multiple_run.itm

There are many more command options available.  View the full list here and experiment with other parameters.

UPDATE:

Another advantage to running from the command line is that you can start and run a model from inside Excel. Not only can you run the model this way, but you can take advantage of all the parameters.

Create a shortcut as described in the post and save it. In Excel, pick a cell and select Insert hyperlink. Browse to and select the shortcut and then click OK. It’s that easy!!

If one production line needs to know this information, a graphical function works fine.  However, if there are two production lines in the model, the second line also needs this information.  If the two lines are identical in structure, the model could be arrayed to share the curve for both lines.  If they are not, it was necessary in versions prior to 9.1 to make a copy of this curve for the second production line.  Then if, at a later time, one copy of the curve needed to be changed, the other one also needed to be changed in the same way.

Version 9.1 introduced the LOOKUP built-in.  This allows any graphical function curve to be re-used as many times as desired within the same model.  Note that a graphical function, by definition, ties a specific equation to the given curve.  Using LOOKUP, it is now possible to evaluate that same curve using several different equations in the same time step.

In this case, let’s assume the second production line has similar variables with “2” appended to their names.  Thus, there is a capacity2 and a material needed 2.  Prior to version 9.1, it was necessary for material needed 2 to be an identical copy of material needed.
Since version 9.1 allows the curve to be re-evaluated for any arbitrary
expression, material needed 2 no longer needs to be a graphical function.
Instead, it contains the equation:

material_needed_2 = LOOKUP(material_needed, capacity_2)

This equation simply evaluates the graphical function stored in material needed using capacity 2 as the x-coordinat

If you have to e-mail your model to isee support, it’s good to know how to package all the necessary files so that we can recreate your setup.

Here’s a list of the files your model may need:

• Modules (.itt files)
• Links (Files that a local file hyperlink button points to)
• Data (Excel and .csv files for import/export)
• Graphics
• Sounds
• Movies

Locate all the associated files in the same place as your model file.

If you have a lot of associated files you can organize them into sub-folders as pictured below:

The one thing to watch out for is the situation of having one file that is accessed in more than one way.  For instance, an Excel file that is used for importing data but is also accessed via a hyperlink button.  In this case, the Excel file should not be in a sub-folder.  Instead, keep it in the same folder as the model file.

Now you can copy the folder to another computer or flash drive, or burn it to a CD.

If you are going to e-mail the folder, you might want to zip it up so you only have one file to send.

While it is easy to determine the fixed interval to use to capture all of these points (1 day), it is more difficult to determine what data points to use for the missing intermediate 1-day values.  There are also many cases where it is very difficult to find a fixed interval that works for a given dataset.

Graphical Function Day (click for full size)

The LOOKUPXY built-in was specifically added to address this issue.  It is unique in that it requires two separate graphical functions:  one for the x-coordinates of each pair and one for the y-coordinates of each pair.  The number of points in each graphical function should match; if they do not, extraneous points are ignored.  The data values (x-coordinates and y-coordinates) are both entered by the user as the y-values in each graphical function.  The x-values in each graphical function are ignored; only the number of points matter.  It is a good idea, though, to run the x-axis of both from one to the number of points.  That way, it is easy to verify that the values in each graphical function properly align with one another.  In addition, the x-coordinates should be in increasing order.  If they are not, however, the program will automatically readjust them when the model is first run.

Graphical Function Flow (click for full size)

The data above are entered into two graphical functions day and flow as shown at the right.  Note the equation for each graphical function is also unimportant.  It is always safe to use TIME (the default when you press “Become Graphical Function”).

The model is very simple:

The following equation for daily flow retrieves this data over the course of the simulation (topping out at 17.3 after time 12):

daily_flow = LOOKUPXY(day, flow, TIME)

Note the graphical function for the x-coordinates is given before the graphical function for the y-coordinates.  In addition, the graph of daily flow is necessarily different from what appears in the graphical function flow, which has the data points drawn at a fixed interval.

As with the graphical function, linear interpolation is used between the given points and out-of-range x-values evaluate to either the first or last y-coordinate, depending whether the value is below the minimum x-coordinate or above the maximum x-coordinate, respectively.  The discrete option is also available.  Make sure to set it in the variable containing the y-coordinates.  [Note that setting it in the variable containing the x-coordinates merely serves to drop the last point.]

For the following discussion, the range on the x-axis will be needed:

range = x_max – x_min

In all of the examples below, x_min = 3.000 and x_max = 7.000, so the range = 7 – 3 = 4.

For integer values, here is a simple formula that always works:

For example (using the range above), if the number 6 (an integer) must appear as a point on the x-axis, 4 + 1 = 5 points will be needed.  This divides the ­x-axis into the points 3.0, 4.0, 5.0, 6.0, and 7.0.

Fractional values, however, are more difficult.  In general, if you can isolate the fractional part (and this evenly divides the range), the maximum number of points needed is given by this formula:

Note for integers, which have a fraction of one, this just simplifies to formula (1).  For example, suppose that the number 4.333 must appear on the x-axis.  The fractional part of this value is 0.333, or 1/3, so 4/(1/3) + 1 = 4*3 + 1 = 13 points will be needed.  This divides the x-axis into 3.0, 3.333, 3.667, 4.0, 4.333, 4.667, etc.

Note, however, that this is not the smallest number of data points needed.  In fact, four points are sufficient:  3.0, 4.333, 5.667, 7.0.  The problem with fractional values is that the equivalent of the least common divisor (LCD) must somehow be found (I leave this derivation to the reader).  The following formula, when it evaluates to an integer, gives this:

For the above example,

range/(desired_point – x_min) + 1 = 4/(4.3333 – 3.0) + 1 = 4/1.3333 + 1 = 3.000 + 1 = 4

The number 4/1.3333 = 3 is important.  The desired value 4.333 will appear in the set of x-axis points whenever the number of data points is set to any of 3k + 1, where k = 1, 2, 3, …  This series contains the values 4, 7, 10, 13, 15, …  Any of these values can be used for the number of data points and 4.333 will appear somewhere on the x-axis.

There are more difficult cases.  If 4.3 is desired on the x-axis and 4.333 is just not close enough, the first formula yields 4/0.1 + 1 = 41 data points.  Note 0.3 could not be used as the fractional part because it does not go evenly into 4.  The largest factor of 0.3 that does go into 4 is 0.1, hence 0.1 is used in the formula.

Is there a smaller number of data points that might work?  Formula (3) can help here:

range/(desired_point – x_min) + 1 = 4/(4.3 – 3) + 1 = 4/1.3 + 1 = 3.077 + 1 = 4.077

This does not look promising as it is not an integer.  In fact, there is no value for the number of data points less than 41 that will work in this case.  Note that all values 40k + 1 will work (for k = 1, 2, 3, …).

Setting up a data import from Excel is pretty straight forward:  type the name of the model variable in one cell, type the value you want to import in the cell below it, (or beside it if you are using horizontal orientation):

If you are importing a time series or graphical function, you just keep listing the data points in the cells below the variable name:

This kind of data formatting works well since an Excel sheet is made up of columns and rows.  But how do you format data that is harder to visualize?  Things get a little tricky when you start dealing with arrayed variables.  The most complex import is a 2 dimensional array of graphical functions.  It’s actually 3 dimensions!

I’ve put together a simple example to illustrate how to do this.

Let’s say you have a model set up to look at 3 teams’ performance on 3 different projects.  The model has an array of Projects and Teams. The Project dimension has 3 elements: Project 1, Project 2 and Project 3.  The Team dimension has 3 elements: Team 1,Team 2 and Team 3.

In this model we’ll put down a converter called “Performance rates” which we’ll later define as a 2D array of graphical functions over time.  The converter will contain historical data on the various teams performance rates for the various projects.

You can see how this sort of setup is pretty close to what someone would want to do – track performance over time per project per team.

The format of the Excel spreasheet would look like this:

Notice that the Team 2 and Team 3 columns have an ellipsis (…) in the header that indicates the column is still part of the Project 1 array element.  Start the next array element, Project 2 with 3 asterisks  (***) at the top of the column.

This is important: The converter name is listed first, then then an ellipsis for each element of the team dimension, (since Team is our first dimension).  The Project dimensions are delimited by the *** and of course the time data goes down.

After setting up your spreadsheet, you  need to set the converter correctly.

Converter Dialog:

In the converter dialog, first check Array, change it from 1D to 2D, (Teams and Projects) and leave Apply to All checked.

Click on the “Become Graphical Function” button on the lower left.  This will switch to the Graphical Function dialog.

Graphical Function Dialog:

Uncheck Apply to All and be sure you have 3 data points set up for each Row/Column combination.  This corresponds to the three time data points we set up going down in the Excel sheet.

The data has been imported into the conveter

Open the Import Data dialog under the Edit Menu. Set up the link so that you are pointing to the spreadsheet you just created.

Select the Import Type you want and browse for the Excel file and worksheet you created.  The data orientation you pick should match the orientation of the spreadsheet.

Once you click OK, a message will let you know if data was successfully imported or not.

Now check to see that the data was imported by hovering over the arrayed variable.

It worked!! You’re good to go.

 >> Download the Sample Files

If you want to avoid lots of copying, pasting, and switching back and forth between your model and Excel, we suggest using the export data feature to set up your data import spreadsheet.

Below are a few simple steps that can save you a bunch of time and headache:

Click to expand

1. In your model, create a Table with all of the variables that you want to import data to.
2. From the Edit menu, choose Export Data. The Export Data dialog will appear.
3. Under “Export Type”, select One Time.
4. Under “Export Data Source”, select Export variables in table and select the table that you created in Step 1.
5. Under “Interval”, select One set of values.
6. Under “Export Destination”, Browse to an empty Excel file and Worksheet Name that you have created for your data import.
7. Select the “Data Orientation” that you prefer.
8. Click OK.

Voila! Your import sheet should be all set to enter data values for each of the variable names AND it will be in the correct format.