Specifying Triggering Events

The top part of the Triggering dialog (which is the only portion visible when you first define a trigger) is where you define the triggering events (the discrete occurrences) that you want the element to respond to:

The More button provides access to advanced triggering options: specifying precedence conditions and required conditions.

By default, when you first create an element that can be triggered, no triggers will exist, and therefore the element will never be triggered.

To define a trigger for the element, you simply press the Add button to add a row to the list of triggering events:

By default, the Type of event added will be “On Event”. If you click on the small button in the Type column, a drop-list will be presented allowing you to edit the event type:

On Event: The Trigger Definition must be a discrete event or discrete change signal from another element. The element is triggered whenever the signal is received.

On Changed: The Trigger Definition can be any continuous output (it cannot be an expression or a discrete signal). The element is triggered whenever the value of Trigger Definition changes.

On True: The Trigger Definition can be any condition output or conditional expression. The element is triggered whenever the Trigger Definition becomes True.

On False: The Trigger Definition can be any condition output or conditional expression. The element is triggered whenever the Trigger Definition becomes False.

At Stock Test: The Trigger Definition must be a conditional expression of of the form “A>B”, “A>= B”, “A<B”, “A<=B”, or “A=B” where A is the primary output of a Reservoir, a Pool or a Fund (from the Financial Module). The element is triggered whenever the Trigger Definition becomes True. As discussed below, this triggering event interrupts the clock and adds an unscheduled update.

At Date: The Trigger Definition must be a date or date and time, enclosed in quotations. (Alternatively, the date can also be expressed as the amount of time since 30 December 1899). The element is triggered whenever the simulated date reaches the specified date. As discussed below, this triggering event interrupts the clock and adds an unscheduled update.

At ETime: The Trigger Definition must be an elapsed time. The element is triggered whenever the simulated elapsed time reaches the specified elapsed time. As discussed below, this triggering event interrupts the clock and adds an unscheduled update.

Auto Trigger: An Auto Trigger requires no user-defined Trigger Definition and its behavior is defined by its context (i.e., the type of element). Auto Triggers can react to the activation or deactivation of their parent Container. In some special cases (e.g., specialized Reliability elements), they can also be used to respond to other types of actions impacting a parent Container (e.g., preventive maintenance). Depending on the type of element, this option may not always be available.

Note: At Stock Test, At Date and At ETime triggers interrupt the clock and insert an unscheduled update when they occur (whereas On True, On False and On Changed triggers do not create an unscheduled update). To understand the implications of this, consider an example in which your scheduled updates were every 10 days. There are two different ways you could try to trigger an event when the value of Reservoir A became greater than the value B. You could create an At Stock Test trigger of A > B, or you could create an On True trigger of A > B. If we assume that A > B actually became true at 15 days, these two triggers would behave very differently. The At Stock Test trigger would catch this point exactly, and insert an unscheduled update at 15 days. In the absence of any other unscheduled updates, however, the On True trigger would not be evaluated and implemented until 20 days. Similarly, if you wished to trigger an event at a specific elapsed time (e.g., 17 days), you could try to do so in two different ways. You could trigger the event using an At ETime trigger of 17 days, or you could create an On True trigger with ETime >=17days. Again, these two triggers would behave very differently. The At ETime trigger would catch this point exactly, and insert an unscheduled update at 17 days. In the absence of any other unscheduled updates, however, the On True trigger would not be evaluated and implemented until 20 days.

Warning: Care must be taken if you choose to disable insertion of unscheduled updates while using At Stock Test, At Date or At ETime triggers. These triggers are designed to interrupt the clock and insert a new update, and may not trigger at all if you disable unscheduled updates.

You can add as many triggering events as desired (with different event types). The element is triggered when any one of the events occurs.

• Unless you are using conditional Containers, you should generally never use an Auto Trigger. If you do, the element will automatically be triggered when its parent Container activates (which in the absence of conditional Containers, is at the beginning of the realization). In most cases, this is not how you will want elements to be triggered.

• On Event triggers can have multiple triggering signals. These are specified by separating the discrete event or discrete change signals with semicolons. If an On Event trigger has multiple triggering signals, the event is triggered after all of the event signals have occurred. For example, if two triggering signals are specified, one which occurs at 10 days, and a second at 20 days, the event will be triggered at 20 days.

• On Changed, On True and On False events are triggered whenever the element determines that the argument to the event has changed, become true, or become false, respectively. If the element is in a conditional Container, it does not evaluate these arguments while it is inactive, and therefore some On Changed, On True and On False events that occur while the Container is inactive can be “delayed” until the element activates (rather than ignored). For example, if an On True trigger is defined as “Etime > 15 days”, and the element is inactive until 20 days, the event will actually be triggered at 20 days (since, from the element’s viewpoint, this is first time that it is able to determine that the condition has become true).

• Unless the Trigger Definition has a well-defined initial value (e.g., such as a Reservoir), On Changed triggers cannot fire at the beginning of a simulation (ETime = 0).

• You should never reference an item of an array within an On Changed, On True or On False trigger (e.g., On Changed vector1[A]). If you do, the trigger will fire if any item of the vector changes (or becomes true or false). If you need to do this, create a scalar Expression with the appropriate definition and use that in the trigger.

• On True events are triggered when the condition switches from False to True. Conversely, On False events are triggered when the condition switches from True to False. The one exception to this rule is the behavior of these triggers at Etime = 0. In particular, an On True trigger that is true at Etime = 0 (e.g., “Etime >= 0 days”) or an On False trigger that is False at Etime = 0 (e.g., “Etime != 0 days”) will fire at Etime = 0.

• You should generally not use equality conditions which reference Time or Etime as a trigger (e.g., an On True triggering event with “Etime = 10 day”). This is because the expression is only evaluated every timestep (and not between timesteps), such that if a timestep does not fall exactly on the time referenced in the condition, the condition will never be True. In such a case, it is always better to use expressions such as “Etime >= 10 day”.

• If the argument to the On Changed trigger is a Run Property that conceptually cycles (e.g., Hour), and your timestep is such that the actual value remains unchanged (e.g., Changed(Hour), with a 1 day timestep), GoldSim will still consider that the argument has changed after such a timestep (since the fact that it remains unchanged is simply an artifact of timestepping).

• Several elements have a checkbox on the Trigger dialog labeled For simultaneous events, act once. If this box is checked and multiple events occur at the same time, the element will be triggered only once. If the box is cleared, the element will be triggered once for each event. In cases where the triggering of an element multiple times by simultaneous events would not make any difference (e.g., Stochastics), this checkbox is not available in the Triggering dialog, and the simultaneous events only trigger the element once.

The example model Triggers.gsm in the General Examples/Events folder of your GoldSim directory (accessed by selecting File | Open Example... from the main menu) contains examples of the various types of triggers.