http://www.iseesystems.

com/Helpv9/Conte
nt/Builtins/Special_Functions.htm#trend
STELLA - ITHINK
Special Functions
This section describes the following Builtins:

CGROWTH

COUNTER

DELAY1

DELAY3

DELAYN

DT

ENDVAL

FORCST

HISTORY

INIT

LOOKUP

LOOKUPXY

PAUSE

REWORK

RUNCOUNT

SMTH1

SMTH3

SMTHN

SOUND

STARTTIME

STOPTIME

SWITCH

TIME

TREND

As the name of the category suggests, the special functions were designed to be used in a
variety of different circumstances. You will find them helpful in the smoothing of noisy
data streams (the SMTH functions), in setting up specific scenarios for a model simulation
(COUNTER, SWITCH, ENDVAL), in doing simple trend analysis and extrapolation
(FORCST, TREND), in establishing relationships which require knowledge of the
simulation specs or of specific model variables (CGROWTH, DT, INIT, REWORK,
STARTTIME, STOPTIME, TIME, RUNCOUNT), in reusing or defining data sets for
graphical functions (LOOKUP, LOOKUPXY), and in providing visual and auditory
feedback to the user (PAUSE, SOUND). Together, the special functions offer a wealth of
capabilities which can fill out the details of your model.

CGROWTH(<percentage>)
In many instances, you will want a stock to grow in compounding fashion, at a certain
percentage rate per unit of time. You'd like to input the percentage growth rate, and to have
the results of the process be independent of the DT which is being used in the model
simulation.
The CGROWTH function enables you to define such DT-independent growth rates. Simply
provide CGROWTH with a per-period percentage growth rate. When embedded in a
compounding process, CGROWTH will ensure that the stock grows at the per-period rate
you have specified, independent of the DT which is being used.
Example:

Growth Fraction = CGROWTH(10) produces 10% per unit time compound growth for the
Stock in Figure 7-17. The specific numerical results of this compound growth process will
be independent of the DT being used for the simulation.

Figure 7-17
Using the CGROWTH Function

COUNTER(<start>, <end>)
Activities in a simulation model often are driven by external cycles. A financial department,
for example, runs on a 30-day billing cycle. A business concern may have seasonal demand
cycles. When the simulation is to run over several cycles, it is useful to know where in the
cycle you are, at any point in time.
The COUNTER function enables you to define such time-dependent cycles. You provide
COUNTER with starting and ending values for the cycle. COUNTER will map start to the
From time you have specified in the Time Specs dialog. It will subsequently return linearly
increasing values, as time progresses. Once COUNTER has counted up to the end, it will
reset itself to start and begin the cycle anew.
Example:
Weekly Cycle = Counter(1,8) produces a linearly increasing cycle which begins at 1, runs
up to 8, and then repeats itself. The cycle thus translates simulation time into days of the
week. Its behavior is shown in Figure 7-18. In the example, From time has been set to 1.

Figure 7-18

Generating a Weekly Cycle Using the COUNTER Builtin

DELAY1(<input>, <delay duration>[, <initial>])

The DELAY1 function calculates a first-order material delay of input, using an exponential
delay time of delay duration, and an optional initial value initial for the delay. If you do not
specify an initial value initial, DELAY1 assumes the value to be the initial value of input.
The DELAY1 function is equivalent to the structure and equations shown in Figure 7-18a.
This structure is a draining process.

Figure 7-18a
Structure of a First-Order Material Delay Process

Stock = Stock + DT*(inflow - delayed_input)

INIT Stock = input*duration_delay or specified initial value*duration_delay
inflow = input

delayed_input = Stock/delay_duration
input = some variable or constant
delay_duration = some variable or constant

Example:
Delay_of_Step = DELAY1(Step_Input, 5) where Step_Input = 5 + STEP(10,3) produces
the pattern shown in Figure 7-18b.

Figure 7-18b
Response of a First-Order Material Delay to STEP Input

Note: The dynamic behavior of DELAY1 is identical to SMTH1, except when the delay
time changes. In this case, DELAY1 will conserve material and SMTH1 will not. DELAY1
is conceptually a flow and SMTH1 is conceptually a stock. Because DELAY1 is a flow
concept, you must C-to-F any converter that uses this function if you wish to see the correct
reported results in a table (or when exported).

DELAY3(<input>, <delay duration>[, <initial>])

The DELAY3 function calculates a third-order material delay of input, using an exponential
delay time of delay duration, and an optional initial value initial for the delay. DELAY3
does this by setting up a cascade of three first-order material delays, each with a delay
duration of delay duration/3. DELAY3 returns the value of the final delay in the cascade. If
you do not specify an initial value initial, DELAY3 assumes the value to be the initial value
of input.

The DELAY3 function will return the value of delay 3 in the structure and equations shown
in Figure 7-18c.

Figure 7-18c
Structure of a Third-Order Material Delay Process

INIT Stock_1 = INIT Stock_2 = INIT Stock_3 = input or specified initial value times duration_delay/3
inflow = input
delay_1 = Stock_1/(delay_duration/3)
delay_2 = Stock_2/(delay_duration/3)
delay_3 = Stock_3/(delay_duration/3)
input = some variable or constant
delay_duration = some variable or constant

Example:
Delay_of_Step = DELAY3(Step_Input, 5) where Step_Input = 5 + STEP(10,3) produces
the pattern shown in Figure 7-18d.

Figure 7-18d
Response of a Third-Order Material Delay to STEP Input

Note: The dynamic behavior of DELAY3 is identical to SMTH3, except when the delay
time changes. In this case, DELAY3 will conserve material and SMTH3 will not. DELAY3
is conceptually a flow and SMTH3 is conceptually a stock. Because DELAY3 is a flow
concept, you must C-to-F any converter that uses this function if you wish to see the correct
reported results in a table (or when exported).

DELAYN(<input>, <delay duration>, <n>[, <initial>])

The DELAYN function calculates an nth-order material delay of input, using an
exponential delay time of delay duration, and order number of n, and an optional initial
value initial for the delay. DELAYN does this by setting up a cascade of n first-order
material delays, each with a delay duration of delay duration/n. DELAYN returns the value
of the final delay in the cascade. If you do not specify an initial value initial, DELAYN
assumes the value to be the initial value of input. n should be specified as an integer.
Example:
Delay_of_Step = DELAYN(Step_Input, 5, 9) where Step_Input = 5 + STEP(10,3) produces
the pattern shown in Figure 7-18e.

Figure 7-18e
Response of a Ninth-Order Material Delay to STEP Input

Note: The dynamic behavior of DELAYN is identical to SMTHN, except when the delay
time changes. In this case, DELAYN will conserve material and SMTHN will not.
DELAYN is conceptually a flow and SMTHN is conceptually a stock. Because DELAYN
is a flow concept, you must C-to-F any converter that uses this function if you wish to see
the correct reported results in a table (or when exported).

DT
DT is the time increment for calculations in a model simulation. DT is found in Run
Specs... under the Run menu. For more information about DT, see Introduction to DT.

ENDVAL(<input>,[<initial>])
The ENDVAL function returns the ending value of input, from the most recent simulation
run in a session with a model. The first time you run the model after opening it, ENDVAL
will return the initial value you have specified. If you do not specify an initial value initial,
ENDVAL assumes the first-run value to be the initial value of input.
Example:
Is_Performance_Improving = Current_Performance_Indicator ENDVAL(Current_Performance_Indicator,0)
enables your model to look at current performance relative to the ending value of
performance in the last simulation run of a given simulation session. In so doing, ENDVAL
provides a mechanism for looking at run-to-run performance changes, and thus can provide
a vehicle for triggering "as-needed" coaching to the model consumer.

FORCST(<input>,<time>,<horizon>[,<initial>])
The FORCST function performs simple trend extrapolation. Here's how it works. First,
FORCST calculates the trend in input, based upon the value of input, the first order
exponential average of input, and the averaging time. (Think of the averaging time as the
time over which you wish to calculate a trend.) Then FORCST extrapolates the trend into
the future - you specify the distance into the future by providing a value for horizon. If you
do not specify initial, FORCST substitutes 0 for the initial value of the trend in input.
The FORCST function is equivalent to the structural diagram and equations shown in
Figure 7-19.

Figure 7-19
Structure for Forecast Based on Trend Extrapolation

Example:
Sales_Forecast = FORCST(Sales,10,15,0) produces a forecast of sales 15 time units into
the future. The forecast is based on current sales, and the trend in sales over the last 10 time
units. The initial growth trend in sales is set to 0.

Tip: If you encounter noise in the variable to be forecasted, you may wish to filter the
randomness by basing your forecast on an exponential smooth of the variable. To do this,
use the SMTH1 or the SMTH3 function (described later in this section).

HISTORY(<variable>,<time>)
The HISTORY function returns the value of a variable at a prior time in the simulation.
Note: HISTORY (stock, TIME-1) is the same as DELAY (stock,1).

INIT(<stock>) or INIT(<flow>) or INIT(<converter>)

The INIT function takes the initial value of the stock, flow, or converter, where the initial
value for the entity has been calculated at the outset of a simulation. The INIT function will
accept only a single model variable name within its parentheses.
Examples:
Distance_Traveled = Position - INIT(Position)
Computes Distance Traveled as the difference between current position and the initial value
of position.
Debt_Ratio = Debt/INIT(Debt)
Computes Debt Ratio as the ratio of Debt to its initial value. When creating graphical
functions, it often is useful to normalize the input to the graphical function in this manner.

LOOKUP(<graphical variable>,<expression>)
The LOOKUP function evaluates the <graphical variable> at the given <expression>
(versus using the equation stored in the graphical function itself).

LOOKUPXY(<x graphical variable>, <y graphical

variable>, <expression>)
The LOOKUPXY function evaluates a graphical function described by (x,y) pairs at the
<expression>. <x graphical variable> is a graphical function that contains the desired xcoordinates in the graphical functions y-values. <y graphical variable> is a graphical
function that contains the corresponding y-coordinates in the graphical functions y-values.
In both graphical functions, the x-value is ignored; the only thing that is used from the
graphical function is the number of data points and the y-values. These two fields constitute
the (x, y) pairs of the graphical function (and will necessarily be sorted in x-ascending order
at the start of each run).

The <expression> is evaluated and found along the x-axis. The corresponding y-coordinate
is returned if the value matches an x-coordinate. Linear interpolation is performed between
x-coordinates. The last y-value is used at either end if the x-value is out-of-range of the
given set of points.
The <y graphical function> can be controlled with a Graphical Input Device by itself, but if
the <x graphical function> is controlled by a Graphical Input Device, the <y graphical
function> must also be controlled.

PAUSE
When it is called, the PAUSE function causes the computer to execute the Pause command
from the Run menu. The PAUSE function thus allows you to pause your simulation run
based on model conditions.
Example:
Sim _Pause = IF US_Deficit > IBM_Revenues THEN PAUSE ELSE 0 causes the
simulation to pause its execution whenever the federal deficit becomes larger than the
revenues of this large computer manufacturer.

REWORK(<percentage>)
In many instances, you will want to represent a rework process. In Figure 7-20, for
example, a production process is used to draw down a work backlog. In the Figure, a
portion of the work (defectives) is shunted back to an earlier stage in the process to be
reworked In Figure 7-21, a Conveyor represents an inspection activity. The leakage flow
from the activity moves rejected material to an earlier stage in the process, where it will
subsequently be re-worked.
In either situation, using a simple fraction to represent the rework percentage will overstate
the cumulative flow of material through the rework process. Each time that material passes
through the inspection activity or production process, a fraction of it will be sent back to be
re-worked. Double-counting can ensue. For example, if 100 units are sent through the
process initially, a 10% defective fraction would send 10 units back to be re-worked in the
first round. In the second round, 1 unit (10% of the 10 units) would be sent back. And, so
on. After the fact, more material than 10% has been re-worked! In most cases, this is not
what you intended.

Figure 7-20
A Simple Rework Process

To get around this double-counting phenomenon, the software provides the REWORK
Builtin. Use it only to represent a rework flow which deposits material at a point
somewhere upstream in the main chain. Simply specify the percentage of total work flow
that you desire to flow back upstream, to be reworked. percentage should be a value
between 0 and 100.
Important Notes: (1) When using a draining process to represent the rework flow, the
REWORK Builtin is not an appropriate choice. (2) When the defectives flow goes to a
cloud, double-counting is not an issue. Hence, REWORK is not required.
Example:
Figure 7-21 shows the results of using REWORK(10) to define the leakage fraction for the
leakage flow from the Inspection Activity. With a total of 100 units of material entering the
system through the entering wip flow, a total of 10 units of work flow through the failing
inspection flow, over the course of the simulation.

Figure 7-21
Using the REWORK Builtin

RUNCOUNT
The RUNCOUNT function accumulates the number of runs that a model has performed
since it was created/opened. Once the model is closed, the function will reset and start at
one the next time the model is opened. This is useful if you are building an interactive
interface for your model and you want some change to take place after a few runs (e.g., turn
on a piece of structure or post a message).

SMTH1(<input>,<averaging time>[,<initial>])
The SMTH1 function calculates a first-order exponential smooth of input, using an
exponential averaging time of averaging time, and an optional initial value initial for the
smooth. If you do not specify an initial value initial, SMTH1 assumes the value to be the
initial value of input.
The SMTH1 function is equivalent to the structure and equations shown in Figure 7-22.
This structure is a stock-adjustment process. Smooth of Input seeks the goal Input.
Example:
Smooth_of_Step = SMTH1(Step_Input,5)
where
Step_Input = 5 + STEP(10,3) produces the pattern shown in Figure 7-23.

Figure 7-22
Structure of First-Order Exponential Smoothing Process

Figure 7-23
Response of First-Order Exponential Smooth to STEP Input

Note: The dynamic behavior of SMTH1 is identical to DELAY1, except when the
averaging time changes. SMTH1 is conceptually a stock and DELAY1 is conceptually a
flow.

SMTH3(<input>,<averaging time>[,<initial>])
The SMTH3 function performs a third-order exponential smooth of input, using an
exponential averaging time of averaging time, and an optional initial value initial for the
smooth. SMTH3 does this by setting up a cascade of three first-order exponential smooths,
each with an averaging time of averaging time/3. SMTH3 returns the value of the final
smooth in the cascade. If you do not specify an initial value initial, SMTH3 assumes the
value to be the initial value of input.
The SMTH3 function will return the value of Stock 3 in the structure and equations shown
in Figure 7-24.

Figure 7-24
Structure of Third-Order Exponential Smoothing Process

Examples:
Smooth_of_Step = SMTH3(Step_Input,5)
where
Step_Input = 5 + STEP(10,3) produces the pattern shown in Figure 7-25.

Figure 7-25

Response of Third-Order Exponential Smooth to STEP Input

Note: The dynamic behavior of SMTH3 is identical to DELAY3, except when the
averaging time changes. SMTH3 is conceptually a stock and DELAY3 is conceptually a
flow.

SMTHN(<input>,<averaging time>,<n>[,<initial>])
The SMTHN function performs an nth-order exponential smooth of input, using an
exponential averaging time of averaging time, an order number of n, and an optional initial
value initial for the smooth. SMTHN does this by setting up a cascade of n first-order
exponential smooths, each with an averaging time of averaging time/n. SMTHN returns the
value of the final smooth in the cascade. If you do not specify an initial value initial,
SMTHN assumes the value to be the initial value of input. n should be specified as an
integer.
Examples:
Smooth_of_Step = SMTHN(Step_Input,5,9)
where
Step_Input = 5 + STEP(10,3) produces the pattern shown in Figure 7-26.

Figure 7-26
Response of Ninth-Order Exponential Smooth to STEP Input

Note: The dynamic behavior of SMTHN is identical to DELAYN, except when the
averaging time changes. SMTHN is conceptually a stock and DELAYN is conceptually a
flow.

SOUND(<expression>)
The SOUND function causes the computer to play the system "beep" sound, when
expression is > 0. When SOUND is active, it takes on a numeric value of 1. Otherwise,
SOUND assumes a numeric value of 0.
Example:
Warning_Sound = SOUND(US_Deficit - IBM_Revenues) causes the computer to play the
system "beep" sound, each DT of the model simulation, as long as the federal deficit is
larger than the revenues of this large computer manufacturer.

STARTTIME
STARTTIME returns the value that you have specified in the Run Specs dialog for the
"From" time in your model.

STOPTIME
STOPTIME returns the value that you have specified in the Run Specs dialog for the "To"
time in your model.

SWITCH(<Input1>,<Input2>)
The SWITCH function is equivalent to the following logic:
If Input1 > Input2 then 1 else 0.

TIME
TIME is the current time within a model simulation. TIME often is used as an argument to
logical functions, trigonometric functions, and graphical functions.
Examples:
10*SIN(2*PI*TIME/12) generates a sinusoidal fluctuation with an amplitude of 10 and a
period of 12.
My_Bonus = IF(TIME=5) OR (Sales>5000) THEN Bonus ELSE 0
This statement sets My Bonus to the value of Bonus at simulated time 5, or whenever the
value of Sales is greater than 5000. When neither condition is met, the statement gives the
value 0. Sales and Bonus are defined elsewhere in the model.
As Figure 7-27 illustrates, TIME can also be used as the independent variable in a graphical
function which defines a set of historical data.

Figure 7-27
A TIME-Dependent Graphical Function

Because of the internal calculations associated with the Runge-Kutta methods, the TIME
function will not return values equal to simulation time when you use the 2nd- or 4th-order
Runge-Kutta computation methods. When your model constructs rely on the TIME
function being exactly equal to simulation time, be sure to use Euler's method.

TREND(<input>,<averaging time>[,<initial>])
The TREND function calculates the trend in input, based upon the value of input, the first
order exponential average of input, and the exponential averaging time averaging time.
TREND is expressed as the fractional change in input per unit time. If you do not specify
initial, TREND substitutes the value 0 for the initial value of the trend.
The TREND function is equivalent to the structural diagram and equations shown in Figure
7-28.
Example:
Yearly_Change_in_GNP = TREND(GNP,1,.04)
This equation calculates the annual change in the input GNP. It starts with an initial value
of .04 (4% per year).

Figure 7-28

Structure for Calculating TREND in Input