Centro risorse METRON

Come utilizzare METRON-Energy Optimization?

Sorgenti dati

Dati calcolati - Sintassi

Imparate a creare dati calcolati tramite l'utilizzo di espressioni matematiche e logiche

Il pannello delle espressioni consente di scrivere l'equazione matematica/logica di una serie calcolata che combina più variabili. Per conoscere le diverse formule disponibili e per ottenere assistenza sulla sintassi da utilizzare nella piattaforma, fare clic sul pulsante "?".

L'avviso di sintassi di METRON è riportato di seguito:

EVA-L Syntax

EVA-L v2.0.2

Basics

Value types

type	values
nil	nil to denote the absence of value
number	e.g. 103, 2.5, .5, 1_000
boolean	true, false
string	e.g. "hello", 'hello'
array	e.g. [1, 2, 3]
dictionary	e.g. {x: 2, y: 1}

TODO : if a nil constant is implemented, maybe document only that instead of introducing nil

Variables

Certain values can be referred to through an associated term. Some are constants (as described in this document), others depend on the context of evaluation.

For example, a variable sensorA could be associated to the current point from a corresponding source.

A variable can be used as a literal value: 2 * sensorA.

TODO : accepted regex equivalent

Operations

An operator typically is expressed with a non-alphanumeric symbol, infix (placed between its operands) and binary (has two operands).
Example: 1 + 2

Operators with a different syntax are detailed further in this doc.
Example: the ! (or not) operator is prefix and unary (has a single operand): !x.

Functions

Functions may be provided in the form f or lib.F. The former is for functions directly accessible, the latter for those living inside a distinct library (here lib is an example of a library name).

A function is called by passing it arguments between parentheses.
Example: f(a, b)

TODO: variadic functions

Parentheses and operations' priority

Parentheses can be used more generally to group terms together.
(1 + 2) is the same expression as 1 + 2.

They're most useful to clarify which priority should be given to different operations.
Example:

2 * 3 + 4 -> 10
2 * (3 + 4) -> 14

Properties access

Array index

An array's element can be accessed by index using bracket notation. Indexes start from 0.

Example: with arr of value [1, 2]

arr[0] -> 1
arr[1] -> 2

The index must be greater or equal to 0, and less than or equal to the last index, otherwise the evaluation fails.

Constants

TODO: when implemented

Operators

TODO: examples in each

Arithmetic operators

	symbol	examples
Addition	+
Subtraction	-
Multiplication	*
Division	/
Remainder informally "modulo"	%	10 % 3 -> 110 % -3 -> 1-10 % -3 -> -1-10 % 3 -> -1
Power	**	2 ** 3 -> 8

Numeric comparison operators

	symbol
Equal	==
Not equal	!=
Less than	<
Greater than	>
Less than or equal to	<=
Greater than or equal to	>=

Logical operators

symbol	examples
&& or and	true && true -> truetrue && false -> false
\|\| or or	true->true -> true \|\| false -> truefalse \|\| true->truefalse \|\| false->false
! or not infix, unary	!true -> false

Bitwise operators

	symbol	examples
Not	~ unary	~4 -> -5
And	&	10 & 3 -> 2
Or	\|	10 \| 3->11
Xor	^	10 ^ 3 -> 9
Left Shift	<<	10 << 3 -> 80
Right Shift	>>	10 >> 3 -> 1

Ternary operators

Conditional expression of the form x ? y : z.
Means "if x is true then y, otherwise z".

Example:
(1 > 3) ? "a" : "b"
-> "b"

A nil condition is not allowed and will make the evaluation fail. See the section Functions > Default Value to handle nil values.

String manipulation operators

	symbol	examples
concatenation	+ same symbol as addition of numbers, but this requires two strings	"a" + "b" -> "ab"
test content	contains	"abcd" contains "bc" -> true
test prefix	startsWith	"ab" startWith "a" -> true
test suffix	endsWith	"ab" endsWith "b" -> true

Data structure membership operators

in and not in are available for both types.
Examples:

2 in [1, 2, 3] -> true
"foo" in {foo: 1, bar: 2} -> true
"baz" not in {foo: 1, bar: 2} -> true

Data stucture range operator

Example: 1..3 -> [1, 2, 3]

Libraries

Default value

When a fallback value is needed in case of nil: \
default(x, y) or x != nil ? x : y

If an interpolation has been applied to a series, there will be no “nil”, and the default function will never return the fallback value.

Math

Namespace: math

- Constants

	symbol	description
Pi	math.PI	Number π. https://oeis.org/A000796
E	math.E	Euler's number. https://oeis.org/A001113

- Arithmetic functions

	function	description	examples
Absolute	math.Abs(x)	Abs returns the absolute value of x.	math.Abs(-42) -> 42
Square root	math.Sqrt(x)	Sqrt returns the square root of x.	math.Sqrt(256) -> 16
Round	math.Round(x)	Round returns the nearest integer, rounding half away from zero.	math.Round(99.6) -> 100
Ceil	math.Ceil(x)	Ceil returns the least integer value greater than or equal to x.	math.Ceil(0.42) -> 1
Floor	math.Floor(x)	Floor returns the greatest integer value less than or equal to x.	math.Floor(-0.42) -> -1

- Logarithmic functions

	function	description	examples
Exponential	math.Exp(x)	Exp returns e\\x, the base-e exponential of x.	math.Exp(1.44) -> 4.220695816996552
Natural logarithm	math.Ln(x)	Ln returns the natural logarithm of x.	math.Ln(1.44) -> 0.36464311358790924
Logarithm base 10	math.Log(x)	Log returns the decimal logarithm of x.	math.Log(1.44) -> 0.15836249209524964

- Trigonometric functions

	function	description	examples
Sine	math.Sin(x)	Sin returns the sine of the radian argument x.	math.Sin(0.28) -> 0.27635564856411376
Arc sine	math.Asin(x)	Asin returns the arcsine, in radians, of x.	math.Asin(0.28) -> 0.28379410920832787
Cosine	math.Cos(x)	Cos returns the cosine of the radian argument x.	math.Cos(0.28) -> 0.9610554383107709
Arc cosine	math.Acos(x)	Acos returns the arccosine, in radians, of x.	math.Acos(0.28) -> 1.2870022175865687
Tangent	math.Tan(x)	Tan returns the tangent of the radian argument x.	math.Tan(0.28) -> 0.28755432574197687
Arc tangent	math.Atan(x)	Atan returns the arctangent, in radians, of x.	math.Atan(0.28) -> 0.2730087030867106

- Comparison functions

	function	description	examples
Minimum	math.Min(x, y, ...)	Min returns the smaller of all given arguments.	math.Min(99.9, 1.3, -55.3, -0.3) -> -55.3
Maximum	math.Max(x, y, ...)	Max returns the larger of all given arguments.	math.Max(99.9, 1.3, -55.3, -0.3) -> 99.9

Time

Namespace: time

Every provided point of data contains an object "time" called t, representing the moment in time during which the data was recorded. It is of the form of an unix nanoseconds timestamp, provided by the database (or any other source.)
Time is converted using the proper time location, allowing the processing of data coming from multiple sources.

Constants

Weekdays

	symbol	description	value
January	time.JANUARY	The month of January.	1
February	time.FEBRUARY	The month of February.	2
March	time.MARCH	The month of March.	3
April	time.APRIL	The month of April.	4
May	time.MAY	The month of May.	5
June	time.JUNE	The month of June.	6
July	time.JULY	The month of July.	7
August	time.AUGUST	The month of August.	8
September	time.SEPTEMBER	The month of September.	9
October	time.OCTOBER	The month of October.	10
November	time.NOVEMBER	The month of November.	11
December	time.DECEMBER	The month of December.	12

Months

	symbol	description	value
Sunday	time.SUNDAY	The day Sunday.	1
Monday	time.MONDAY	The day Monday.	2
Tuesday	time.TUESDAY	The day Tuesday.	3
Wednesday	time.WEDNESDAY	The day Wednesday.	4
Thursday	time.THURSDAY	The day Thursday.	5
Friday	time.FRIDAY	The day Friday.	6
Saturday	time.SATURDAY	The day Saturday.	7

Seasons

	symbol	description	value
Winter	time.WINTER	The season of Winter. From 01/12 to 28/02.	1
Spring	time.SPRING	The season of Spring. From 01/03 to 31/05.	2
Summer	time.SUMMER	The season of Summer. From 01/06 to 31/08.	3
Autumn	time.AUTUMN	The season of Autumn. From 01/09 to 30/11.	4

Functions

Basic functions

	function	description	example (with t = 1998-07-12 20:02:42.000000385 +0000 UTC)
Nanosecond	time.Nanosecond()	Nanosecond returns the nanosecond offset within the second specified by t, in the range [0, 999999999].	time.Nanosecond() -> 385
Second	time.Second()	Second returns the second offset within the minute specified by t, in the range [0, 59].	time.Second() -> 42
Minute	time.Minute()	Minute returns the minute offset within the hour specified by t, in the range [0, 59].	time.Minute() -> 02
Hour	time.Hour()	Hour returns the hour within the day specified by t, in the range [0, 23].	time.Hour() -> 20
Day	time.Day()	Day returns the day of the month specified by t.	time.Day() -> 12
Week	time.Week()	Week returns the ISO 8601 year and week number in which t occurs. Week ranges from 1 to 53. Jan 01 to Jan 03 of year n might belong to week 52 or 53 of year n-1, and Dec 29 to Dec 31 might belong to week 1 of year n+1.	time.Week() -> 28
Month	time.Month()	Month returns the month of the year specified by t.	time.Month() -> time.JULY
Year	time.Year()	Year returns the year in which t occurs.	time.Year() -> 1998

Expanded functions

	function	description	example (with t = 1998-07-12 20:02:42.000000385 +0000 UTC)
Week of month	time.WeekOfMonth()	WeekOfMonth returns the week of the month in which t occurs, based on ISO 8601 calculations.	time.WeekOfMonth() -> 2
Day of year	time.DayOfYear()	DayOfYear returns the day of the year specified by t, in the range [1, 365] for non-leap years, and [1, 366] in leap years.	time.DayOfYear() -> 193
Day of week	time.DayOfWeek()	DayOfWeek returns the day of the week specified by t.	time.DayOfWeek() -> time.Sunday
Is weekend	time.IsWeekend()	IsWeekend returns true if the day of the week specified by t is either Saturday or Sunday, and false otherwise.	time.IsWeekend() -> true

Seasons' functions

	function	description	example (with t = 1998-07-12 20:02:42.000000385 +0000 UTC)
Season	time.Season()	Season returns the season specified by t.	time.Season() -> time.SUMMER
Is winter	time.IsWinter()	IsWinter returns true if the season specified by t is winter and false otherwise.	time.IsWinter() -> false
Is spring	time.IsSpring()	IsSpring returns true if the season specified by t is spring and false otherwise.	time.IsSpring() -> false
Is summer	time.IsSummer()	IsSummer returns true if the season specified by t is summer and false otherwise.	time.IsSummer() -> true
Is autumn	time.IsAutumn()	IsAutumn returns true if the season specified by t is autumn and false otherwise.	time.IsAutumn() -> false

Date creation functions

	functions	description	example
Date	time.Date(year, month, day, hour, min, sec, nsec)	Date returns the Time corresponding to the provided year, month, day, hour, minute, second and nanosecond.	time.Date(1998, time.JULY, 12, 20, 02, 42, 385) -> 1998-07-12 20:02:42.000000385 +0000 UTC
Date from UNIX nano	time.DateFromUnixNano(nanosec_timestamp)	DateFromUnixNano returns the Time corresponding to the provided Unix nanoseconds timestamps.	time.DateFromUnixNano(900273762000000385) -> 1998-07-12 20:02:42.000000385 +0000 UTC
Parse	time.Parse(datetime_string)	Parse parses a formatted string using the dd/mm/yyyy or dd/mm/yyyy hh:mm:ss layout, and returns the time value it represents.	time.Parse("12/07/1998") -> 1998-07-12 00:00:00.000000000 +0000 UTCtime.Parse("12/07/1998 20:02:42") -> 1998-07-12 20:02:42.000000000 +0000 UTC

Comparison functions

	function	description	example (with t = 1998-07-12 20:02:42.000000385 +0000 UTC)
Before	time.Before()	Before reports whether the time instant t is before arg.	time.Before(time.Date(2020, time.JULY, 10, 12, 0, 0, 0)) -> false
After	time.After()	After reports whether the time instant t is after arg.	time.After(time.Date(2020, time.JULY, 10, 12, 0, 0, 0)) -> true
Equal	time.Equal()	Equal reports whether t and arg represent the same time instant. Two times can be equal even if they are in different locations. For example, 6:00 +0200 and 4:00 UTC are Equal. Most code should use Equal instead of ==.	time.After(time.Date(2020, time.JULY, 10, 12, 0, 0, 0)) -> false

Formatting functions

	function	description	example (with t = 1998-07-12 20:02:42.000000385 +0000 UTC)
RFC3339	time.Rfc3339()	Rfc3339 returns a textual representation of the time value formatted according to RFC3339.	time.Rfc3339() -> 1998-07-12T20:02:42Z
UNIX nano	time.UnixNano()	UnixNano returns t as a Unix time, the number of nanoseconds elapsed since January 1, 1970 UTC. The result is undefined if the Unix time in nanoseconds cannot be represented by an int64 (a date before the year 1678 or after 2262). Note that this means the result of calling UnixNano on the zero Time is undefined. The result does not depend on the location associated with t.	time.UnixNano() -> 900273762000000385

Se una funzione matematica non è presente in questo elenco, si prega di contattare
il vostro referente METRON.