Skip to main content
Skip table of contents

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

Term editor

Term editor

Create new term

Create new term

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

  1. Go to System configuration (Wrench icon) > Calculations > Terms > Term editor > Term.

  2. View data sources and select relevant devices (Measurement overview).

  3. Enter designation, abbreviation, type, unit, formula.

  4. 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

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.