Converters

Often you will want to add structured input or empirical data to your model. For instance, if you were modeling a lake, you might want your model to have access to historical precipitation data that was recorded periodically. Alternatively, you might want to know the actual, surveyed surface area of the lake, given the volume of the lake.

Simgua makes using this data very easy with its converter primitive which allows you to create an input-output relationship or graph. When the input source to a converter primitive takes on an input value, the converter takes on the corresponding output value which may then be used by other primitives that reference the converter. The input can be the current time (in seconds, minutes, hours, etc…) or the value of some other primitive that is linked to the converter. Simgua supports two types of converters, discrete and continuous converters. Discrete converters will only display a value when an precise output for the current input value has been specified (or the current is input is within a tolerance distance from the specified input). Continuous converters will display outputs for all inputs, even if a precise output for a given input has not been specified.

For continuous converters, if you have not specified a specific output value for a given input, the outputs closest to the input will be combined to develop an appropriate output based on an interpolation method you have specified. For illustration, take the following example input-output table for a converter whose input source is the current time in years and where linear interpolation has been selected.

Input	Output
0	1
10	2
20	5
30	10
40	17
50	26

At the start of the simulation (when the time is 0 years), the converter will take on the value of 1. Ten years into the simulation (when the time is 10 years), the converter will take on a value of 2. Fifteen additional years into the simulation (when the time is 25 years), there will not be a precise input value for the current time in years. Thus the converter will average the two closest input-output pairs (20 years, and 30 years) to get 7.5 for the value of the converter ([5+10]/2).

When using a discrete converter, it is important to realize that the value of the converter is undefined at certain parts of the simulation. If you are only using the converter for display purposes (such as to visually compare between simulated and empirical values), this is not a problem; but if you are using the value of the converter elsewhere in your model’s equations, it can cause errors. If you take the value of a converter and use it in another equation, the value of that equation also becomes undefined. If you use an undefined value in a flow, any stocks that are connected to that flow will become undefined. Even when the converter takes on an actual value again, these stocks will still remained undefined and they will remain this way throughout the rest of the simulation!

If you need to use a converter value in your equations even when it is not defined, you can use what is called an IfThenElse function in your equations. IfThenElse is a function that takes three arguments. The first one is a logical statement that evaluates to true or false. The second argument is a value the function takes on if the logical argument is true, and the last argument is the value the function takes on if the logical argument is false. You can pair this with the Converter’s HasOutput function likes follows:

The above function will return the squared value of My Converter if it is defined and 0 otherwise. Do not worry if you do not completely understand this function, it uses a triangular bracket notation which is described later in this manual.

You can enter data into the converter by hand or import a two-columned comma separated dataset (CSV file) that may be generated by Microsoft’s Excel or other spreadsheet programs. The first line of the CSV file is assumed to be a header and is ignored. The first column becomes the input values, and the second column becomes the output values.