Terms

In the mathematical sense, a “term” allows you to define custom data points at the system level using your own formula, which is evaluated for the variables used for every available timestamp. The Term editor in VCOM allows you to process measured data from your system and generate key performance indicators. Terms are integral to charts, simulations, KPIs, evaluations, and certain portlets. For example, you can use terms to calculate the average for several sensors or to define the parameters to determine the total energy (E_Z_EVU).

Term editor

Item	Name	Details
1	Term	Create new term
2	Recalculation of terms	Re-calculate all terms within a selected time period. Overwrites previous values.
3	Designation	The designation of a term is a user-friendly name and will later be visible in graphs and reports.
4	Abbreviation	The abbreviation of a term defines how the results of this term can be referenced in other terms and through the VCOM API. If possible, use the defined abbreviations. See Terms abbreviations with a special meaning
5	(Aggregation) Type	The Type field describes how the values that this term yields should be aggregated. Currently, there are two options: Sum: Results are summed up over time (e.g. energy values). Average: Results are averaged over time (e.g. temperature values). Important: If the unit `W/m²` is used, the type Average should be selected as for time intervals greater than one hour the aggregation will automatically switch to the unit `Wh/m²`.
6	Unit	The unit field selects the unit to be displayed in charts and reports.
7	Formula	Formulas consist of the following. See also Formulas Variables Numbers Operators Functions: simple and complex Eye icon: Preview of formula results for the selected day
8	Measurement overview	Overview of the available data sources (=variables) and the corresponding terms for your system

Create terms: general workflow

Prerequisites

None

Steps

Go to System configuration (Wrench icon) > Calculations > Terms > Term editor > Term.
View data sources and select relevant devices (Measurement overview).
Enter designation, abbreviation, type, unit, formula.
The terms can then be applied throughout VCOM, for example in the Power flow portlet and Charts.

Abbreviations with a special meaning

Abbreviation	Required unit	Use in VCOM	Description
E_Z_EVU	kWh	Simulation, alarms, charts, various KPIs	Energy generated per interval for the whole system
E_Z_PV(1..x)	kWh	Meter comparison chart
G_M0	W/m²	Simulation, charts, various KPIs	Weighted irradiance on the module plane
G_H0	W/m²	Evaluation	Weighed irradiance on the horizontal plane
G_Mx (x = 1..99)	W/m²	Simulation	Other irradiance measurements on the module plane
G_Hx (x = 1..99)	W/m²	Evaluation	Other irradiance measurements on the horizontal plane
E_Z_PVx (x= 1..99)	kWh	Energy comparison chart, evaluation
T_M0	°C	KPIs	Module temperature per interval for the whole system
T_U(0..x)	°C		Ambient temperature
M_AC_E_EXP	kWh	Self-consumption chart	Energy export
M_AC_E_IMP	kWh	Self-consumption chart	Energy import
M_AC_E_OWN	kWh	Self-consumption chart	Energy self-consumption
PF_P_GEN	W	Power flow portlet	PV power
PF_P_GRID	W	Power flow portlet	Import / export power
PF_P_CON	W	Power flow portlet	Consumption power
PF_P_BAT	W	Power flow portlet	Battery power
W_V(0..x)	m/s		Wind speed
W_D(0..x)	°		Wind direction

Formulas

Variables and data source

You must specify at least one variable for each formula otherwise nothing will be calculated. VCOM provides you with an overview of the available data sources (=variables) and the corresponding terms for your system. For this, select Measurement overview (Question mark icon) while editing a term. In general, all variables start and end with an apostrophe ('). Any configured device can be selected separately via the dropdown menu. If no device is selected, the sum of all devices will be taken.

Available data sources (variables) — Available data sources (=variables)

The result of the term is not tied to a specific device; even if it uses the values from one device, it applies to the entire system and is not associated with any particular device.

For the sake of simplicity, the examples used below will not use variables and use NULL to represent a null-value returned by a variable or calculation.

Numbers

In addition to variables, numbers can be used. Both, and . can be used as a decimal separator. Thousands separators and scientific notation are not supported.

Operators

To combine multiple variables (and numbers), various operators are available. In general, all operators will yield null if any of the operands are null, the only exception of that rule being ??. The precedence describes the order of calculation, with higher precedence evaluated before lower precedence

List of operators

Precedence	Symbol	Name	Description	Example
				Formula	Result
8	`(` `)`	Parenthesis	Pairs must be balanced. Other types of parenthesis like `[` `]` or `{` `}` are not supported.	`2 * (2 + 3)`	`10`
7	`!`	Boolean-Negation	Returns `0` for `1` and `0` for everything else. This is a unary operator to be placed in front of the operand.	`!0` `!1` `!(-1)`	`1` `0` `0`
7	`-`	Arithmetic-Negation	Returns the arithmetic negation of the variable. This is a unary operator to be placed in front of the operand.	`-0` `-1` `-(-1)`	`0` `-1` `1`
6	`^`	Exponentiation	Returns the left operand to the power of the right operand.	`2 ^ 3` `NULL ^ 3` `2 ^ NULL`	`8` `NULL` `NULL`
5	`*`	Multiplication	Returns the product of the two operands.	`2 * 3` `NULL * 3` `2 * NULL`	`6` `NULL` `NULL`
5	`/`	Division	Returns the left operand divided by the right operand. Returns `null` if the right operand is `0` .	`2 / 4` `NULL / 3` `2 / NULL` `2 / 0` `NULL`	`0.5` `NULL` `NULL` `NULL`
5	`%`	Remainder	Returns the remainder of dividing the left operand by the right operand. Returns `null` if the right operand is `0` .	`2 % 4` `NULL % 3` `2 % NULL` `2 % 0`	`2` `NULL` `NULL` `NULL`
4	`+`	Addition	Returns the sum of both operands.	`2 + 3` `NULL + 3` `2 + NULL`	`5` `NULL` `NULL`
4	`-`	Subtraction	Returns the the second operand subtracted from the first operand.	`2 - 3` `NULL - 3` `2 - NULL`	`-1` `NULL` `NULL`
3	`==`	Equality	Returns `1` if the left operand is equal to the right operand, `0` otherwise.	`2 == 2` `2 == 3` `2 == NULL` `NULL == NULL`	`1` `0` `NULL` `NULL`
3	`!=`	Non-equality	Returns `0` if the left operand is not equal to the right operand, `1` otherwise.	`2 != 3` `2 != 2` `2 != NULL` `NULL != NULL`	`1` `0` `NULL` `NULL`
3	`<`	Less-Than	Returns `1` if the left operand is strictly less than the right operand, `0` otherwise.	`2 < 3` `2 < 2` `2 < NULL` `NULL` `NULL < NULL`	`1` `0` `NULL` `NULL`
3	`>`	Greater-Than	Returns `1` if the left operand is strictly greater than the right operand, `0` otherwise.	`2 > 1` `2 > 2` `2 > NULL` `NULL > NULL`	`1` `0` `NULL` `NULL`
3	`<=`	Less-Or-Equal	Returns `1` if the left operand is less or equal to the right operand, `0` otherwise.	`2 <= 3` `3 <= 2` `2 <= NULL` `NULL <= NULL`	`1` `0` `NULL` `NULL`
3	`>=`	Greater-Or-Equal	Return `1` if the left operand is greater or equal to the right operand, `0` otherwise.	`2 >= 2` `2 >= 3` `2 >= NULL` `NULL >= NULL`	`1` `0` `NULL` `NULL`
2	`&&`	Logical And	Returns `1` if both operands are not `0` , `0` otherwise.	`1 && 1` `1 && 0` `0 && 0` `NULL && 1`	`1` `0` `0` `NULL`
2	`\|\|`	Logical Or	Returns `1` if either operand is not `0` , `0` otherwise.	`1 \|\| 1` `1 \|\| 0` `0 \|\| 1` `0 \|\| 0` `NULL \|\| 1`	`1` `1` `1` 0 `NULL`
1	`??`	Null-Coalesce	Returns the value of the left operand if it is not `null` , otherwise the right operand is returned.	`0 ?? 1` `NULL ?? 1`	`0` `1`

Functions

In addition to operators, functions can greatly reduce the complexity of formulas. Functions calls consist of a function identifier, followed by a list of parameters (separated by ; ) in parenthesis ( ). Calling functions with fewer/more parameters than required is an error.

Simple functions

List of simple functions

Identifier	Number of parameters	Description	Example
			Formula	Result
`sum`	2-999	Returns the sum of all non-`null` parameters, `null` if there are none.	`sum(3; 3)` `sum(2; NULL)` `sum(NULL; NULL)`	`6` 2 `NULL`
`average`	2-999	Returns the mean of all non-`null` parameters, `null` if there are none.	`average(2; 4)` `average(10; NULL; 30)` `average(NULL; NULL)`	`3` `20` `NULL`
`median`	2-999	Returns the median of all non-`null` parameters, `null` if there are none.	`median(7; 3; 5)` `median(7; NULL; 5)` `median(NULL; NULL)`	`5` `6.5` `NULL`
`min`	2-999	Returns the smallest of all non-`null` parameters, `null` if there are none.	`min(-1; 5; 3)` `min(NULL; 5; 3)` `min(NULL; NULL)`	`-1` `3` `NULL`
`max`	2-999	Returns the greatest of all non-`null` parameters, `null` if there are none.	`max(-1; 5; 3)` `max(-1; NULL; 3)` `max(NULL; NULL)`	`5` `3` `NULL`
`pi`	0	Returns the value of pi.	`pi()`	`3.1415926535898`
`sin`	1	Returns the sine of the parameter, the parameter has to be given in radians, not degrees. Returns `null` if parameter is `null` .	`sin(pi()/2)` `sin(0)` `sin(NULL)`	`1` `0` `NULL`
`cos`	1	Returns the cosine of the parameter, the parameter has to be given in radians, not degrees. Returns `null` if the parameter is `null` .	`cos(pi())` `cos(0)` `cos(NULL)`	`-1` `1` `NULL`
`if`	2-3	Returns the second parameter if the first parameter is not `0` or `null`, otherwise returns the third parameter (if given) or `null` otherwise.	`if(1; 2)` `if(0; 2)` `if(NULL; 2)` `if(-1; 2; 3)` `if(0; 2; 3)` `if(NULL; 2; 3)`	`2` `NULL` `NULL` `2` `3` `3`
`select`	2-999	Returns the n-th parameter after the first parameter, where the value of `n` is the first parameter, `null` if no parameter is found.	`select(1; 2; 3; 4)` `select(2; 2; 3; 4)` `select(3; 2; 3; 4)` `select(4; 2; 3; 4)`	`2` `3` `4` `NULL`
`take_positive`	1	Returns the first parameter if it is strictly greater than zero, `null` otherwise.	`take_positive(5)` `take_positive(0)` `take_positive(-3)` `take_positive(NULL)`	`5` `NULL` `NULL` `NULL`
`weighted_average`	4..998 (only even) first-value; first-weight; second-value; second-weight;...	Returns the weighted mean of all non-`null` values, `null` if any of the weights are `null` or there are no values.	`weighted_average(25; 2; 10; 1)` `weighted_average(25; 2; NULL; 1)` `weighted_average(25; 2; 10; NULL)` `weighted_average(NULL; 2; NULL; 1)NULL`	`20` `25` `NULL` `NULL`

Complex functions

List of complex functions

Identifier	Number of parameters	Description	Example
			Timestamp	Formula	Result
`year`	0	Returns the current year	`2024-02-09 12:00:00`	`year()`	`2024`
`month`	0	Returns the current month of year (1-12)	`2024-02-09 12:00:00`	`month()`	`2`
`day`	0	Returns the current day of month (1-31)	`2024-02-09 12:00:00`	`day()`	`9`
`before`	1-6 year; month = 1; day = 1; hour = 0; minute = 0; second = 0	Returns `1` if the currently evaluated timestamp is strictly before the date given as parameters, `0` otherwise	`2023-12-31 23:59:59` `2024-01-01 00:00:00`	`before(2024)` `before(2024)`	`1` `0`
`after`	1-6 year; month = 1; day = 1; hour = 0; minute = 0; second = 0	Returns 1 if the currently evaluated timestamp is strictly after the date given as parameters, `0` otherwise.	`2023-12-31 23:59:59` `2024-01-01 00:00:00`	`after(2023; 12; 31; 23; 59; 59)` `after(2023; 12; 31; 23; 59; 59)1`	`0` 1
`before_time`	1-3 hour; minute = 0; second = 0	Returns `1` if the currently evaluated timestamp's time is strictly before the time given as parameters, `0` otherwise.	`04:59:59` `05:00:00`	`before_time(5)` `before_time(5)`	`1` `0`
`after_time`	1-3 hour; minute = 0; second = 0	Returns`1` if the currently evaluated timestamp's time is strictly after the time given as parameters, `0` otherwise.	`19:59:59` `20:00:00`	`after_time(19; 59; 59)` `after_time(19; 59; 59)`	`0` `1`
`is_monday` `is_tuesday` `is_wednesday` `is_thursday` `is_friday` `is_saturday` `is_sunday`	0	Returns `1` if the currently evaluated timestamp is on a monday/tuesday/wednesday/thursday/friday/saturday/sunday, `0` otherwise	`2024-02-09 00:00:00` `2024-02-09 23:59:59` `2024-02-10 00:00:00`	`is_friday()` `is_friday()` `is_friday()`	`1` `1` `0`
`sun_up`	0	Returns `1` if the sun is over the horizon, `0` otherwise. *The actual result depends on the time and location of the system.	`2024-02-09 07:30:00` `2024-02-09 07:35:00` `2024-02-09 17:25:00` `2024-02-09 17:30:00`	`sun_up()` `sun_up()` `sun_up()` `sun_up()`	`0` * `1` * 1 * `0` *
`sun_azimuth`	0	Returns the sun's azimuth angle in degrees (0=North, 180=South) at the currently evaluated timestamp. *The actual result depends on the time and location of the system.	`2024-02-09 07:30:00` `2024-02-09 12:00:00` `2024-02-09 17:30:00`	`sun_azimuth()` `sun_azimuth()` `sun_azimuth()`	`110` * `171.74` * `250` *
`sun_elevation`	0	Returns the sun's elevation angle between horizon and the sun in degrees at the currently evaluated timestamp. *The actual result depends on the time and location of the system.	`2024-02-09 12:00:00`	`sun_elevation()`	`26.54` *
`delta`	1-3 total; negative-limit = -∞; positive-limit = ∞	Returns the difference between this timestamp's first parameter and the last timestamp's first parameter, `null` if outside of limits. ¹ The first result of the `delta` function on each day is always `NULL` ² If the passed total is `NULL` , the last total is re-used for the next evaluation	`2024-02-09 00:00:00` `2024-02-09 00:05:00` `2024-02-09 00:10:00` `2024-02-09 00:15:00` `2024-02-09 00:20:00`	`delta(50)` `delta(60)` `delta(50)` `delta(NULL)` `delta(60)`	`NULL` ¹ `10` `-10` `NULL` ² `10`
`tilted_irradiance`	3	Returns the tilted irradiance calculated from the horizontal irradiance value (the first parameter), the tilt of the surface (the second parameter) and the orientation of the surface (the third parameter), `null` if either parameter is `null` . *The actual result depends on the time and location of the system.		`tilted_irradiance(800; 20; 180)` `tilted_irradiance(NULL; 20; 180)` `tilted_irradiance(800; NULL; NULL)`	`926` * `NULL` `NULL`

Example: energy sum

In the example below, the datapoint E_Z_EVU is defined as the energy sum of the inverters.

Example term_en.png — Term example: energy sum