http://www.iseesystems.com/Helpv9/Content/Builtins/Special_Functions.htm#trend

STELLA - ITHINK

Special FunctionsThis 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_delayinflow = inputdelayed_input = Stock/delay_durationinput = some variable or constantdelay_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/3inflow = inputdelay_1 = Stock_1/(delay_duration/3)delay_2 = Stock_2/(delay_duration/3)delay_3 = Stock_3/(delay_duration/3)input = some variable or constantdelay_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 x-coordinates in the graphical function’s y-values. <y graphical variable> is a graphical function that contains the corresponding y-coordinates in the graphical function’s 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