Stocks

In its simplest form a stock is a bucket into which a something can accumulate or be withdrawn from.  What the bucket holds is specific to your model; it could be water, or money, or even deer. You can set an initial value or level for the stock that it will take on at the start of the simulation. The initial value may be a simple number or a more complex mathematical expression.

The units of the stock’s contents are not entered into Simgua and it is the responsibility of the user to remember them. Make sure that one part of your model does not assume that a stock representing a water tank has units of meters cubed, while another part of your model is based on the assumption that the units are in liters.

Stocks are flexible. For Instance, They can hold People, Water, Or Viruses.

One example of the use of a stock would be to simulate a reservoir. Water is added to the reservoir by rivers and then released from the reservoir for irrigation or consumption. Another example of a good use of a stock would be the population of a city. People migrate to the city and emigrate from the city. In this case the units for the stock would in numbers of people.

The value of a stock – or any other valued primitive for that matter – can be referenced in equations using a pair of square brackets around the primitive’s name. For instance, if you had a stock was called “My Lake”, you could obtain twice its value in an equation using:

The standard stock is in effect one large mixing bowl.  Materials are added directly to the bowl, completely mixed with the existing bowl contents, and then removed from the bowl. For most cases this is the desired behavior. For some cases, however, users will desire slightly different behavior. For instance, let us presume we are attempting to simulate an aging population. One way to simulate this would be to create a number of different stocks representing different age groups. For instance, we could have a “Young” stock, a “Middle-aged” stock, and an “Old” stock. Each time step we could transfer a fixed fraction of the young people to the middle-aged stock, and a fraction of the middle-aged people to the old person stock. We could simulate births by adding new individuals to the young stock, and deaths by removing people from the old stock. This would work pretty well if we had a population where the demographics remained roughly constant. Let’s assume, however, that we encounter a shock like the baby-boom generation in the United States. This shock would add a large number of people to the young stock instantly. In reality these individuals should age a large number of years before they are passed on to the middle-aged stock. Unfortunately, because we are moving a fixed fraction of the young people to the middle-aged stock each period, the shock is felt in the middle-age population immediately. This is not the desired behavior and will lead to incorrect demographic modeling.

We can attempt to remedy this by increasing the number of stocks. Instead of three, we could have six, or 30, or 1000. The more stocks we added, the more accurate our modeling. Creating such a large number of stocks, however, would be infeasible! Fortunately, Simgua allows you to “Serialize” stocks, thereby creating a theoretically unlimited number of sub compartments within one stock. There are two methods of serialization: one using a fixed volume for the stock and the other governed by a Probability Density Function.

Diagram of a Serialized Stock (Probability Density Function Type: Fixed Delay)

When a fixed volume is specified, the stock sequesters the specified volume before releasing the remainder as “overflow”. This can be useful for simulating tanks of substances (this type of stock is sometimes known as an “Oven”). As more and more material is added to the stock, it steadily fills up until its volume is exceeded. When this happens, the materials that have been in the stock the longest are overflowed and are then available to be withdrawn from the stock. The value of the stock (which is obtained using the bracket standard notation) is the quantity of the overflow that has not yet been withdrawn from the stock. As a model developer you might also be curious as to the length of time the overflow spent within the stock prior to release. This can be found by accessing the stock’s overflow_delay property. The total contents contained by any serialized stock can be found using a double bracket notation like so:

Another form of serialized stock is one governed by a probability density function (PDF). When you define a PDF for a stock, the stock is converted from being a simple mixing bowl to an object more analogous to a conveyor belt. The stock is split up into a number of separate compartments. As time passes, material within the stock is passed sequentially from compartment to compartment (moving one compartment forward each time step). Once the material reaches the very last compartment and is overflowed it is available for withdrawal.

The PDF defined by the user determines which compartments along the conveyor belt material inflow is initially deposited into. The simplest type of PDF is a fixed delay PDF. In this scenario all new inflows are deposited into a compartment such that the inflow is available for withdrawal from the stock after a fixed, user specified delay. Thus the materials in the inflow are identical to the materials available for outflow except that they are staggered by the time delay. The number of compartments created is the specified delay divided by the time step rounded up. So if the specified delay is not an even multiple of the time step, the actual delay will be slightly longer.  

Serialized Stock Results

You may also define PDF’s using standard probability distributions. For instance if you have a process governed by a Gamma Distribution (such as incubation time for some disease) you can give your stock a Gamma Distribution PDF using empirical parameters. The outflow form a single input into the stock would then follow a Gamma Distribution. It is important to note that the continuous probability distribution inherent in the underlying PDF is made discrete by Simgua. The accuracy of the new approximate PDF is dependent on the size of the time step with smaller time step leading to more accurate approximations.

In addition to Gamma and Normal Distributions, Simgua also allows you to develop your own PDF’s based on empirical data. So, for instance, if you were modeling the incubation period for a new disease, you could directly input the results from an epidemic outbreak into your stock.

Table of Stock Properties

Back to the overview of all primitives.