Declaration of Variables
Primitive
Primitives are data elements in TOP-Energy that are editable and visible as identifiers in forms and stored in projects. The syntax for linking the variable with the primitive is as follows:
Number variable-name(primitive-path)[variable-unit];
The paths can be found in the form description in the template editor.
Date Functions on Simulation Time
For time-dependent simulations, the current simulation time can be queried via system variables of type DateTime.
| Syntax | Description |
|---|---|
| .system.time | Date and time of the simulation time in local time |
| .system.timeCET | Date and time of the simulation time in Central European Time |
The following date functions are available for conversion into Number type variables. They can be invoked on the above system variables and do not require any arguments.
| Function | Basic Type | Arguments | Description |
|---|---|---|---|
| getHourOfDay | DateTime | --- | calculates the hour of the day as Number |
| getMinuteOfDay | DateTime | --- | calculates the minute of the day as Number |
| getDayOfWeek | DateTime | --- | calculates the day of the week as Number (Monday = 1, Tuesday = 2 ... Sunday = 7) |
| getDayOfMonth | DateTime | --- | calculates the day of the month as Number |
| getDayOfYear | DateTime | --- | calculates the day of the year as Number |
| getMonthOfYear | DateTime | --- | calculates the month of the year as Number |
| getYear | DateTime | --- | calculates the year as Number |
In this way, e.g., in the following equation, the day of the month of the simulation time is determined in relation to the Central European Time zone.
dayOfMonthCET = .system.timeCET.getDayOfMonth();
Simple Time Series Functions
Time series properties such as minimum, maximum, or mean value can be queried using simple time series functions. These do not require arguments and can be used within expressions.
| Function | Basic Type | Arguments | Description |
|---|---|---|---|
| min | Number | --- | calculates the minimum |
| max | Number | --- | calculates the maximum |
| mean | Number | --- | calculates the mean value |
| weightedMean | Number | --- | calculates the weighted average value |
| integral | Number | --- | calculates the integral |
These functions do not provide constant time series, but numerical values. For example, the following equation calculates the variable b as the sum of the minimum and maximum of the (time-dependent) variable a.
b = a.min() + a.max();
These functions are often used to calculate efficiencies. The efficiency of a cogeneration unit (eta) is the quotient of electrical (P_el) plus heat power (Q_dot_heat) and fuel power (H_dot_chem).
eta = (Q_dot_heat.weightedMean() + P_el. weightedMean ()) / H_dot_chem. weightedMean ();
Creating a Duration Curve
The isLoadDurationOf function creates a duration curve (red in the following figure) as a new time series in which the data of the input time series (blue in the following figure) are sorted in descending order.
The syntax is:
Result-variable.isLoadDurationOf(input-variable);
The result variable must be connected to a primitive in which the calculated time series is stored directly. The time axis of the duration curve is abstract and, in particular, does not correspond to the simulation times. In the simulation, these results cannot be used for further calculations because points in time are inconsistent.
For example, to create a duration curve for the operating hours in the CHP component, first declare the result variable and connect it to a primitive.
Number OperatingHoursLoadProfile(“/Local/eProc/…”);
The function isLoadDurationOf can then be called as an instruction in the equations.
OperatingHoursLoadProfile.isLoadDurationOf(OperatingHours);
Extended Time Series Functions
There are advanced time series functions that allow typical properties such as minimum, maximum, mean, or integral to be determined for the entire simulation period or for each day, month, or year within the simulation period.
These functions require three parameters. The syntax is generally:
Result-variable.Time-series-function(input-variable, time-period, reference-time);
The time series function is executed on the time series of the input variable of type Number and may only be used as an instruction. The result is stored in the result variable, also of type Number.
For the four functions isMinValueOf, isMaxValueOf, isMeanValueOf, and isWeightedMeanValueOf the result is a constant time series.
For the function isIntegralOf the result is a time series which contains the integral of the input time series from the reference time point for each point in time. The reference time point depends on the time period.
Time Period
The time period determines the time periods considered in each case. It is a parameter of type Integer. There are the following four different variants:
| Value | Time Period |
|---|---|
| 0 | entire simulation period |
| 1 | year |
| 2 | month |
| 3 | day |
Reference Time
The reference time is a parameter of type Integer. It determines the beginning of the respective time periods. The integral begins at the reference time with 0.
In this way, you can calculate yearly from July, month by month from the 15th of the month, or day by day from 12 o’clock.
The default values are obtained by selecting the value 0. You can also enter only the first or the first two parameters in the function. The remaining parameters are then interpreted as zero.
Available Time Series Functions
The available time series functions are shown in the following table.
| Function | Basic Type | Arguments | Description |
|---|---|---|---|
| isMinValueOf | Number | Number, Integer, Integer | calculates the minimum of the entire simulation period or per year, month, or day |
| isMaxValueOf | Number | Number, Integer, Integer | calculates the maximum of the entire simulation period or per year, month, or day |
| isMeanValueOf | Number | Number, Integer, Integer | calculates the mean value of the entire simulation period or per year, month, or day |
| isWeightedMeanValueOf | Number | Number, Integer, Integer | calculates the weighted average value of the entire simulation period or per year, month, or day |
| isIntegralOf | Number | Number, Integer, Integer | calculates the integral of the entire simulation period or per year, month, or day |
For variables a, b, c of type Number,
b.isMaxValueOf(a, 2);
assigns the monthly maximum of a to each time point of b. The unspecified parameter for the reference time here assumes the default value zero. In addition,
c.isMeanValueOf(a, 1, 4);
assigns the annual average of a in the period April-March to each point in time of c. The results for a heat demand are shown in the following figure. It shows the heat demand of a year with monthly maxima (blue) and annual mean (red).
If the second and third arguments are omitted, the expression is analogous to that in the Simple Time Series Functions section.
The expressions
a = b.min() ;
and
a.isMinValueOf(b) ;
are identical.
