Referencing a Time Series Using a Function

In some situations, you might want to reference a value from a Time Series element at some point in the future or past (as opposed to at the current time in the simulation). To support this, Time Series elements can be referenced in the way that you would reference a built-in function (like sin or min). That is, once you define a Time Series, you can reference it in input expressions for other elements as if it were a function:

This expression instructs GoldSim to use the Time Series defined by the element named Rainfall and compute its value at time = 35 days. When specifying a date, you must enclose it in quotation marks. The format for referencing a date is determined by the Regional and Language time/date settings specified by the operating system.

Of course, once you have defined the table, you can reference it at multiple locations (i.e., in the input fields for various elements) using different input arguments (different time values) in the same manner as you would use the built-in functions provided by GoldSim multiple times.

Note that when you create a Time Series, GoldSim automatically lists it as a function in the Function menu that is accessible from the context menu within an input field:

The dimensions of the Time Series function are determined by the Display Units specified when the Time Series element was defined. Note that if the Time Series itself is defined as an array, the output of the function is an equivalent array.

Time Series functions have two arguments (with the second one being optional). In most cases, you will call the function with only the first argument. The first argument is the time value. If you omit the second argument, the first argument is interpreted in the same manner in which the Time Series was defined. Hence, if the Time Series was defined based on Calendar Time, the first argument is assumed to be a date. If the Time Series was defined based on Elapsed time, the first argument is assumed to be an elapsed time.

By using the second argument, you can specifically override the default setting for how the first argument in interpreted. In particular, if

Second Argument = 2: The first argument is interpreted as an elapsed time from the beginning of the simulation.

Warning: To utilize this function properly, it is important to understand how dates and elapsed times are represented in GoldSim. In particular, note that dates are represented internally in GoldSim as times. In particular, a date is stored as the amount of time since 30 December 1899. As a result, if you specify a first argument of 90 days, but indicate that this is a date (e.g., by specifying the second argument as 1), it will be interpreted as the calendar date 30 March 1900. Similarly, if you specify a first argument of “16 October 2011” and indicate that this is an elapsed time (e.g., by specifying the second argument as 2), it will be interpreted as the elapsed time of 40832 days (the number of days since 30 December 1899).

Note that if the first argument represents a time that precedes the earliest entry in the Time Series, the function returns the value associated with the first entry. Similarly, if the first argument represents a time that is later than the last entry in the Time Series, the function returns the value associated with the last entry.

Note: If your Time Series is defined as an array, you can use GoldSim’s array functions to reference a single item from the array. For example, to reference the value at 4 days for the 3^rd item of a Time Series vector named X, you would use the following expression: getitem(X(4 day), 3).