Allocator Elements

Allocator elements allocate an incoming signal to a number of outputs according to a specified set of demands and priorities. Typically, the signal will be a flow of material (e.g., water), but it could also be a discrete transaction.

The incoming signal to an Allocator element (the Amount) must be a scalar. The Type drop-list allows you to specify whether the incoming signal is a Value or a Discrete Change Signal.

If it is a Discrete Change Signal, the icon for the Allocator indicates this by changing its color (from blue to red):

An Allocator can accept multiple discrete changes. This is indicated in the input field by separating the individual discrete change signals by semi-colons (e.g., Change1; Change2; Change3). You can also specify the multiple discrete changes using the Multiple Discrete Signals button, which displays a table listing the multiple discrete change signals.

The outputs of the Allocator element are specified in the "Outputs" section of the dialog. By default, an Allocator element initially has one output (named Output1). You can add additional outputs by pressing the Add button (the plus sign) below the list. Outputs can be deleted using the Delete button (the X), and moved up and down in the list using the two buttons to the right of the Delete button.

The names of the outputs can be changed by editing the items in the Name column.

For each output, you specify the Demand for that output. The Demand has the same type and dimensions as the incoming Amount. Demands can be specified as constants or expressions and/or links, and may change with time. Each output receives its requested Demand according to the specified Priority. Outputs with lower valued Priorities are met first (i.e., Priority 1 is met before Priority 2).

In this case, Output1 would have a value of 75m³/day (its entire demand would be met), Output2 would have a value of 20m³/day (its entire demand would be met), Output3 would have a value of 5m³/day (only part of its demand would be met), Output4 would have a value of 0m³/day (none of its demand would be met), and the "Unused" output would have a value of 0m³/day.

By default, each output has a fixed (and unique) Priority (which is an integer). The Priority of the outputs always decrease downward (with the first item having a Priority of 1). Priority 1 therefore represents the highest priority demand, 2 the next highest, and so on. New outputs are added below the output that is selected when pressing the Add button. You can move outputs up and down the Priority list using the Move Up and Move Down buttons (found directly below the list).

If you check the Allow editing of Priorities checkbox, the Priority column becomes editable. In this case, the Priorities can be specified as constants or expressions and/or links, and may change with time. They do not need to be integers and can be any real value (positive or negative). Outputs with lower valued Priorities are met first (e.g., Priority -2.4 is met before Priority 5.7).

If multiple outputs have the same Priority, you can specify the manner in which equal priorities are treated in the For equal priorities field. There are two options: 1) “share the input equally”; or 2) “share proportional to demands”.

If “share the input equally” (the default) is selected, each output with equal priority receives the same amount up until either its demand is satisfied, or nothing more is available. The calculation is carried out recursively starting with the smallest demand.

In this case, Output1 would have a value of 75m³/day (its entire demand would be met), Output2, Output3 and Output4 would share the remainder (25m³/day) as follows:

• Output4 would receive its full demand (5m³/day); Output2 and Output3 would receive the same amount (5m³/day). This leaves 10m3/day to be allocated.

• Output2 and Output3 would then equally share the remaining 10m³/day (such that each would receive a total of 10m³/day). So Output3 and Output4 would meet their demands, and Output2 would not.

If “share proportional to demands” is selected, if there is not enough supply to meet all of the demands, it is shared proportionally according to the demand.

To illustrate this, consider the same example as above, with proportional sharing:

In this case, Output1 would still have a value of 75m³/day (its entire demand would be met), Output2, Output3 and Output4 would share the remainder (25m³/day) as follows:

The table below summarizes the results for these two examples (note that the total supply is 100m³/day and the total demand is 110 m³/day):

Under some circumstances, you may want to define a Demand by referencing the total amount available, or the remainder after the previous Priority has been met. GoldSim facilitates this by providing two locally available properties:

• "Total". This represents the current value in the Amount field. You would reference this value as "~Total".

• "Remainder". This represents the amount remaining (of the original amount) after all senior priorities (i.e., Demands with lower-valued Priorities) have been met. Hence, the Remainder takes on a different value in each row. You would reference this value as "~Remainder".

Note: In situations where several rows have equal priorities, the ~Remainder for a particular row is equal to the total amount available to the row divided by the number of remaining unmet equal priority rows. In this calculation, the equal priority rows are ordered not based on the order they where entered, but from smallest demand to largest demand.

Note: Total and Remainder are examples of locally available properties. As such, they only have meaning inside the Demand field, and cannot be referenced anywhere else.

For example, if Output1 had a Demand of 100 m³/day, and Output2 had a Demand that was half of what was remaining after Output1's demand was met, you could define the Demands as follows:

As shown below in the browser view of an Allocator element, there is an output for each item in the Outputs list. There is also an additional output (called "Unused") that represents the portion of the incoming signal that was unused (i.e., unallocated, or left over after the demands were met).

Note: Element inputs and outputs are only shown in the browser if you choose to Show Element Subitems (accessed via the browser context menu by right-clicking in the browser).

The outputs of an Allocator can be either values or discrete change signals (depending on how the Type field was defined).

Note: If an Allocator outputs discrete change signals, the outputs (including the Unused output) preserve the Instruction of the input signal.

Note: If an Allocator outputs discrete change signals, signals with a zero value and an “Add” Instruction are not propagated.

Several example models which use a Allocator element (Allocator.gsm) can be found in the General Examples folder in your GoldSim directory (accessed by selecting File | Open Example... from the main menu). This file includes the use of an Allocator to simulate competing demands on a Reservoir.

Note: The algorithm described above is the same algorithm used to allocate the outflows from the Pool element. In fact, a Pool can be thought of as a combination of a Reservoir and an Allocator.

Output	Priority	Demand (m3/day)	Result with equal sharing (m3/day)	Result with proportional sharing (m3/day)
Output1	1	75	75	75
Output2	2	20	10	14.3
Output3	2	10	10	7.1
Output4	2	5	5	3.6