Functions, Expressions and Conditions

SAInt-GUI has built-in functions that are used in the command window and script editor to plot, tabulate, analyze, and compare both input properties and output results from a model. These functions are based on IronPython, an open-source implementation of the Python programming language integrated in the .NET framework.

This section of the reference guide provides an in-depth introduction to the most important functions. But the user is encouraged to check the "workspace tab" in the GUI to find quickly a complete and concise list of functions with their syntax.

Each function can be categorized into one of the following groups:

General functions	functions used to interact with network objects or navigate the map window.
Table functions	functions used with different types of expressions to tabulate data. Returns a custom table of different object(s) properties and results.
Plot functions	functions used with different types of expressions to visualize data. Returns custom plots of different object(s) properties and results.
Evaluation functions	functions used with different types of expressions to analyze and aggregate object parameter data. The return type includes lists or floating-point values.
Graph functions	functions used with different types of expressions to aggregate and post-process object parameter data. The return type is a SAInt data format. They are called by plot and table functions to create custom plots and tables.

1. Different types of expressions

Functions need arguments to carry out their intended scope. In SAInt arguments are passed to a function as a single expression between either single or double quotation marks. An expression is indicated using expr in the body of the function call.

SAInt distinguishes five types of expressions: object-related expressions, arithmetic expressions, conditional expression, control value expression, and time expressions. Such expressions cover from the properties of an object, to the way properties are combined using mathematical formulas or logical conditions. Expressions can reference control values used for making comparisons, or define how the time or time window to be used for extracting data.

This section describes the different expression types and provides some basic examples. The examples shown are based on the dynamic scenarios of the sample electricity (ENET09_13) and gas (GNET29_18) networks available in the user’s Projects folder (C:\...\Documents\encoord\SAInt-v3\Projects). Please consider the type of object used in the expression to select the correct network. Scenario results must be available for the expression to be executed correctly in the command window. Note that the sample electricity (ENET09_13) model uses a stochastic profile for the hydro reservoir. This is why the user may get different results from the ones presented here or each time the same command is used in the active session of SAInt.

Note that expressions will be indicated with the topographical convention ENO.Node1.P.(4), while the use of color, like in ENO.Node1.P.(4), is reserved for indicating objects or object’s properties.

The user can easily copy and paste the code in the command window and replicate the examples.

1.1. Object expression

Object expressions are used to access a specific network object and to retrieve data related to its properties. The general syntax of the expression for selecting an object is:

ObjectType.ObjectName

where ObjectType indicates the type of object to search for (e.g., a gas node GNO or an electric line LI), and ObjectName the given name in the model of such object (e.g., you may have called a gas node like OFFTAKE_42).

The general syntax of the expression for selecting a property of an object is:

ObjectType.ObjectName.PropertyExtension

where PropertyExtension is the extension SAInt uses to indicate the specific property (e.g., P for the pressure of a certain node in gas networks).

For example, ENO.Node1, will identify the electric node called Node1. In contrast, ENO.Node1.P will collect the active power at the node.

Object expressions can be typed in the command window to collect parameter data directly without the need of any function. But when using the script editor, the evaluation function eval('expr') is required.

Example 1. Object expression.

GNO.CGS_2: The expression allows to select in memory the gas node named CGS_2.
GSUP.%: The expression returns a list of all supply external in the gas model.
ENO.Node1.P: The expression returns the active power at the node at the last simulation time step equal to -97.225 MW.
ENO.Node1.P.(4): The expression returns the active power at the node at the 4^th hour of the simulation.
mark('GNET.!GDEM'): The function uses an expression to select in the map window all the 12 nodes that have at least one gas demand external associated.
plot('WIND.WINDFARM.P.[MW]'): The plot function uses an expression to chart the power generated by the wind generator WINDFARM within the time properties defined ChartStartTime and ChartEndTime.

2. Special parameters in expressions

You may have noticed that in the examples of the previous section, there are some expressions with some extra characters. SAInt allows the user to easily extend the meaning of an object expression by adding special parameters. The general syntax for using these special parameters is:

ObjectType.%.PropertyExtension.[Unit].(%)/(Time)

where:

`%`	The symbol `%` allows to select all objects in a network belonging to a particular object type. When typed in the command line, the command `GSUP.%` returns the list of the three supply points belonging to the networks. It reads like this "return all the names of the object belonging to type supply in the active network".
`[Unit]`	The unit of measure is an optional special parameter. If no unit information is specified, then the property value will be displayed in the unit specified for the corresponding unit type and property of the general settings. If a different unit is specified, SAInt takes care of the conversion. For example, 'WIND.%.P.[MW]` indicates that the total power of the wind generators is expressed in megawatts. The units can be changed in the units tab under SAInt GUI settings.
`(%)` or `(Time)`	The time definition is optional. In its general form `(%)` goes always at the end of the expression, and it means to "consider all time steps of the scenario". This special parameter is different from `%`. To specify a particular time in the simulation, a string with a well-formatted date-time format can be used, or alternatively, a time offset string such as '+1:30' or '+2:00'. A time offset string indicates that a certain amount of time is being added to the scenario start time. The plus sign at the beginning of the string indicates that time is being added, and the subsequent numbers, such as '1' and '45', represent the number of hours and minutes to be added to the scenario start time. A well-formatted date-time format requires the particular moment expressed as "dd/mm/yyyy hh:mm" or day, month, and year, followed by hours and minutes, like "25/15/2020 18:00" (six o’clock in the afternoon of December 25, 2020).

Another case is:

ObjectType.!ObjectType

where:

!

The symbol ! is used in an input expression containing a two-level nested hierarchy of object types. The symbol goes before the second type which is a child of the first. When we type GNET.!GDEM we are asking to pick the object type GNET, and retrieve all child objects of type GDEM. It reads like this "return all the names of the object gas demand external which are inside the active network".

2.1. Arithmetic expression

Arithmetic expressions allow to combine object expressions using mathematical operations such as addition, subtraction, multiplication, square root, cosine, sine, logarithm, etc. An arithmetic expression can take as arguments only network parameters (i.e., object expressions for properties) or mix network parameters and numerical constants. Check the List of available mathematical functions. for more details.

The eval function must be used to compute the value of an arithmetic expression. The function eval accepts as arguments: an object expression for a property or mathematical combinations of object expressions for a property and numerical constants. It always returns a numeric value. This result can be further used as input for other IronPython arithmetical functions.

List of available mathematical functions.

Function Description

Function	Description
`trunc(x)`	The function returns the integer part of x with the fractional part removed.
`acos(x)`	The function returns the arc cosine (inverse cosine) of a number in radians.
`acosh(x)`	The function returns the inverse hyperboilic cosine of a number in radians.
`cos(x)`	The function returns the cosine of the given angle.
`cosh(x)`	The function returns the hyperbolic cosine of a number in radians.
`asin(x)`	The function returns the arc sine (inverse sine) of a number in radians.
`asinh(x)`	The function returns the inverse hyperboilic sine of a number in radians.
`sin(x)`	The function returns the sine of the given angle.
`sinh(x)`	Returns the hyperbolic sine of a number in radians.
`atan(x)`	The function returns the arc tan (inverse tan) of a number in radians.
`atan2(x)`	The function returns the arctangent, or inverse tangent, of the specified x- and y-coordinates.
`atanh(x)`	The function returns the hyperboilic tan of a number in radians.
`tan(x)`	The function returns the tangent of the given angle.
`tanh(x)`	The function returns the hyperbolic tangent of a number in radians.
`degrees(x)`	The function returns the angle (radian) in degrees.
`exp(x)`	Natural exponential function.
`factorial(x)`	The function returns the factorial of a number.
`log(x)`	The function returns the natural logarithm (Base e) of a number.
`log10(x)`	The function returns the base-10 logarithm of a number.
`log1p(x)`	The function returns the natural logarithm (base e) of 1 + p, where p is the argument.
`pi`	The function returns the value of the mathematical constant PI ~ 3.14159.
`e`	The function returns the value of the mathematical constant e ~ 2.71828182845905.
`radians(x)`	The function returns the angle (degrees) in radians.
`sqrt(x)`	The function returns the square root of a number.
`mean`	The function returns the mean of a list of float values.
`ceil(x)`	The function returns the ceiling of the variable as a float and the smallest integer value greater than or equal to the variable.
`copysign(x,y)`	The function returns a variable x with the sign of a second variable y.
`erf(x)`	The function returns the error function value as a float at the variable.
`erfc(x)`	The function returns the complementary error function value as a float at the variable.
`expm1(x)`	The function returns the natural exponential function minus one for small float values.
`fabs(x)`	The function returns the absolute value of a variable.
`floor(x)`	The function returns the floor of a variable x as a float, the largest integer value less than or equal to the variable x.
`fmod(x,y)`	The function returns the modulo, the remanent after the division, of varible x by another variable y.
`frexp(x)`	The function returns the mantissa and exponent of x as the pair (m, e). m is a float and e is an integer such that x == m * 2**e exactly. If x is zero, returns (0.0, 0), otherwise 0.5 ⇐ abs(m) < 1. This is used to “pick apart” the internal representation of a float in a portable way.
`fsum`	The function returns an accurate floating point sum of values in list.
`ldexp(x,y)`	The function returns x*2^y. It is the inverse of function `frexp`.
`gamma(x)`	The function returns the Gamma function at the variable.
`lgamma(x)`	The function returns a natural logarithm of the absolute value of the Gamma function at the variable.
`hypot(x, y)`	The function returns the Euclidean norm, sqrt(xx + yy). This is the length of the vector from the origin to point (x, y).
`modf(x)`	The function returns the fractional and integer parts of a variable x. Both results carry the sign of the variable x and are floats.
`pow(x,y)`	The function returns a variable x raised to the power of another variable y.

trunc(x)

The function returns the integer part of x with the fractional part removed.

acos(x)

The function returns the arc cosine (inverse cosine) of a number in radians.

acosh(x)

The function returns the inverse hyperboilic cosine of a number in radians.

cos(x)

The function returns the cosine of the given angle.

cosh(x)

The function returns the hyperbolic cosine of a number in radians.

asin(x)

The function returns the arc sine (inverse sine) of a number in radians.

asinh(x)

The function returns the inverse hyperboilic sine of a number in radians.

sin(x)

The function returns the sine of the given angle.

sinh(x)

Returns the hyperbolic sine of a number in radians.

atan(x)

The function returns the arc tan (inverse tan) of a number in radians.

atan2(x)

The function returns the arctangent, or inverse tangent, of the specified x- and y-coordinates.

atanh(x)

The function returns the hyperboilic tan of a number in radians.

tan(x)

The function returns the tangent of the given angle.

tanh(x)

The function returns the hyperbolic tangent of a number in radians.

degrees(x)

The function returns the angle (radian) in degrees.

exp(x)

Natural exponential function.

factorial(x)

The function returns the factorial of a number.

log(x)

The function returns the natural logarithm (Base e) of a number.

log10(x)

The function returns the base-10 logarithm of a number.

log1p(x)

The function returns the natural logarithm (base e) of 1 + p, where p is the argument.

pi

The function returns the value of the mathematical constant PI ~ 3.14159.

e

The function returns the value of the mathematical constant e ~ 2.71828182845905.

radians(x)

The function returns the angle (degrees) in radians.

sqrt(x)

The function returns the square root of a number.

mean

The function returns the mean of a list of float values.

ceil(x)

The function returns the ceiling of the variable as a float and the smallest integer value greater than or equal to the variable.

copysign(x,y)

The function returns a variable x with the sign of a second variable y.

erf(x)

The function returns the error function value as a float at the variable.

erfc(x)

The function returns the complementary error function value as a float at the variable.

expm1(x)

The function returns the natural exponential function minus one for small float values.

fabs(x)

The function returns the absolute value of a variable.

floor(x)

The function returns the floor of a variable x as a float, the largest integer value less than or equal to the variable x.

fmod(x,y)

The function returns the modulo, the remanent after the division, of varible x by another variable y.

frexp(x)

The function returns the mantissa and exponent of x as the pair (m, e). m is a float and e is an integer such that x == m * 2**e exactly. If x is zero, returns (0.0, 0), otherwise 0.5 ⇐ abs(m) < 1. This is used to “pick apart” the internal representation of a float in a portable way.

fsum

The function returns an accurate floating point sum of values in list.

ldexp(x,y)

The function returns x*2^y. It is the inverse of function frexp.

gamma(x)

The function returns the Gamma function at the variable.

lgamma(x)

The function returns a natural logarithm of the absolute value of the Gamma function at the variable.

hypot(x, y)

The function returns the Euclidean norm, sqrt(x*x + y*y). This is the length of the vector from the origin to point (x, y).

modf(x)

The function returns the fractional and integer parts of a variable x. Both results carry the sign of the variable x and are floats.

pow(x,y)

The function returns a variable x raised to the power of another variable y.

Example 2. Arithmetic expression.

ENET.PG.(10).[MW]: This is a regular object expression and not an arithmetic expression. It returns a value of type string, even if we see numerical digits.
eval('ENET.PG.(10).[MW] + 5'): This is the correct way of combining an object expression for a property and a constant with the same units. The evaluation function returns the sum of active power generated by the electric network at the 10^th hour of the simulation in megawatts and a constant value of 5 (megawatts).
eval('ENO.Node9.PPV.[MW].(%) * 10'): The expression returns a list with the values of the active power in megawatts generated by all solar generators connected to the electric node Node9 during all time steps of the simulation. Each time step value is multiplied by 10. In the example, we have only one solar generator associated with ENO.Node9.
eval('GDEM.CGS_08.Q.[ksm3/h].(3) + GDEM.CGS_09.Q.[ksm3/h].(3)'): The arithmetic expression returns the sum in ksm³/h of the demand of the externals GDEM.CGS_08 and GDEM.CGS_09 at the 5^th hour of the simulation. The value is 308 ksm³/h.
eval('sqrt(ENET.PG.[MW].(5))'): Returns the square root of the power generated by the electric network at the 5^th hour of the simulation.

Check the content of the workspace in SAInt for a list of mathematical functions.

ENET.PG.(10).[MW] + 5: This is a mix of two object expressions and will result in a syntax error.

2.2. Conditional expression

Conditional expressions allow to use of Boolean algebra in expressions, and in their most basic form to check whether a statement is true or false. The conditional expression can combine different network parameters, arithmetic expressions, or constant values. The expression returns Boolean "True" or "False" values. As for arithmetic expressions, a conditional expression must be used as argument to the eval function.

Example 3. Conditional expression.

eval('FGEN.PEAKERTURBINE.P.(%).[MW] > FGEN.PEAKERTURBINE.PMIN.(%).[MW]'): Checks if the power generated by the fuel generator PEAKERTURBINE is greater than its minimum power generation (PMIN) at each time step and returns a list of true or false values. The length of the list is equal to the number of time steps in the simulation.
eval('ENET.PG.(100).[GW] > 100'): Checks if the active power generation by the electric network is greater than 100 MW at the 100^th hour of the simulation and returns a true or false value.
eval('FGEN.COMBINECYCLE.P.[MW].(%) > 80 or FGEN.COMBINECYCLE.P.[MW].(%) < 100'): The expression checks if the power generated by the fuel generator COMBINECYCLE is between 80 MW and 100 MW at each time step of the simulation and returns a list of true or false values. The length of the list equals the number of time steps in the simulation.
eval('GDEM.CGS_08.Q.[ksm3/h].(3) > GDEM.CGS_09.Q.[ksm3/h].(3)'): The expression checks if the demand flow at the external GDEM.CGS_08 is higher than the one at the external GDEM.CGS_09 at the 5^th hour of the simulation. The answer is False.

Only a single network parameter can be used for combined conditional expressions (Object Type, Object ID, and Property Extension must be the same).

2.3. Control value expression

Control value expressions are special and optional expressions used with plotting functions such as nplot or stackplot. They are very useful in charts because they allow to add reference values like a constant line representing a threshold or a desired value to reach. Control value expression cannot be used as a stand-alone expression, but must be used with some other object expressions. Furthermore, it is necessary to specify the unit of measure used like 45[MW].

Example 4. Control value expression.

nplot('WIND.WINDFARM.P.[MW]','45[MW]'): Plots the power generated by the wind generator WINDFARM and a control value of 45 MW.

2.4. Time expression

Time expressions are used in time-dependent functions to indicate either the exact time step to be used or to define the time window considered. examples of time-dependent functions are the time function or the different functions for plotting or creating tables.

If any time expression is specified, the default behavior of the time-dependent functions is to use the default start time and end time given by the ChartStartTime and ChartEndTime properties in the scenario editor.

Example 5. Time expression.

time('+1'): Increase the time of the map window by one hour.
time('03/01/2022 15:00'): The resulting display time on the map window is 03-January-2022 15:00.
plot('WIND.WINDFARM.P.[MW];blue','03/01/2022 00:00','04/01/2022 00:00'): Plots the power generated by the wind generator WINDFARM for the defined time window (03-January-2022 00:00 until 04-January-2022 00:00).

2.5. Time record

After a non-steady simulation, like dynamic gas or QuasiDynamicACPF, SAInt records the simulation time into the workspace with time record functions in hours as numeric expressions, either as floats or a list of floats. Check the List of time record functions..

List of time record functions.

Function Description

Function	Description
`etimes`	Returns a list of float values, a record of all time steps in the electric simulation.
`gtimes`	Returns a list of float values, a record of all time steps in the gas simulation.
`etime`	Stores the float value of the time step of an electric simulation as it progresses in time, it makes the time step callable in expressions and functions.
`gtime`	Stores the float value of the time step of a gas simulation as it progresses in time, it makes the time step callable in expressions and functions.
`edt`	Returns the float value of the electric simulation time step, equivalent to the `TimeStep` of the electric scenario.
`gdt`	Returns the float value of the electric simulation time step, equivalent to the `TimeStep` of the gas scenario.
`etmax`	Returns the float value of the last record in `etimes`, equivalent to the `TimeWindow` of the electric simulation.
`gtmax`	Returns the float value of the last record in `gtimes`, equivalent to the `TimeWindow` of the gas simulation.

etimes

Returns a list of float values, a record of all time steps in the electric simulation.

gtimes

Returns a list of float values, a record of all time steps in the gas simulation.

etime

Stores the float value of the time step of an electric simulation as it progresses in time, it makes the time step callable in expressions and functions.

gtime

Stores the float value of the time step of a gas simulation as it progresses in time, it makes the time step callable in expressions and functions.

edt

Returns the float value of the electric simulation time step, equivalent to the TimeStep of the electric scenario.

gdt

Returns the float value of the electric simulation time step, equivalent to the TimeStep of the gas scenario.

etmax

Returns the float value of the last record in etimes, equivalent to the TimeWindow of the electric simulation.

gtmax

Returns the float value of the last record in gtimes, equivalent to the TimeWindow of the gas simulation.

Example 6. Time record.

print(gtimes): Prints in the command window all the time steps of GSCE.DYN_6, from 0.0 to 144.0 in increments of 0.25 h.
gtmax: Returns 144 equal to the TimeWindow of GSCE.DYN_6.
gdt: Returns 0.25 equal to the TimeStep of GSCE.DYN_6.