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.
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 / 0NULL
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 < NULLNULL
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.
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
Returns1 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.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.