Conditions

SAInt allows building dynamic scenarios where multiple events change the evolution of a network. Events are dependent on the object considered and are specified by setting "what should happen" (i.e., the type of the event), "when it should happen" (i.e., the time of the event), and "how big is the thing happening" (i.e., the magnitude of the event). Events take place as specified by the user, and they do not depend on any assessment of the system’s status at that moment in time. This way of modeling creates a "rigid", though powerful, framework to explore the capabilities of a system.

SAInt also allows extending the use of events by means of "conditions" to go beyond the "rigid modeling framework". Conditions are an extra layer of logic on top of the scenario allowing to incorporate "what-if" statements and activating events based on the status of the system’s components. By using conditions, the user can "model choices" and introduce "simulation branches" describing sets of events to be executed when certain constraints are met, or certain thresholds are violated.

This section of the reference guide provides a quick introduction to conditions and explains the different evaluation rules. By means of examples, the section showcases the most common applications of conditions.

For more details on the concept of events, see section Objects and its subsections. To see how to add conditions and evaluation rules in SAInt refer to the How-to Add and Evaluate a Condition for an Event.

1. When and where to use conditions

A "condition" in SAInt is composed of a "Boolean logic conditional expression" returning a true or false value, and an "evaluation rule", testing the application of the specified event. The table of the scenario events and the Property Editor, once an event is selected, show the field Condition and Evaluation where the user needs to specify the expression and the rule for the evaluation.

Conditions are used in dynamic simulations to direct a possible solution for the system at time step t_N+1, starting from time step t_N.

The use of conditions is discouraged and not possible for steady state problems or optimization problems. In a steady state gas simulation, adding conditions to a scenario may frequently enforce a set of infeasible constraints. It would also require the use of multiple instances of the same type of event for an object (e.g., given a supply point we would define a PSET if condition A is true and another PSET if condition B is true). This option is not allowed in SAInt.

In optimization problems like DCUCOPF, it is typically not possible to have a meaningful evaluation of expressions because the values of variables are not known until the optimization is complete unless the terms of expressions refer to known properties. Additionally, DCUCOPF has several constraints linked over multiple time steps (for example, uptime and downtime), making it difficult to control the individual time steps independently using values from previous time steps. Trying to influence the solution process with ill-defined conditions can cause wrong results or infinite loops. Furthermore, if the user applies conditions using unknowns, the problem will become non-linear, which cannot be handled in a DCUCOPF scenario. Electric constraints ENET are advised in optimization models to relate one object’s unknown parameter with another object’s unknown parameters.

2. Different types of conditions

The user is free to build any type of Boolean logic conditional expression. SAInt has a built-in Script Editor for writing statements and checking for any syntax errors. As in the command line, the Script Editor can autocomplete names and properties of objects. The statement is checked for proper formatting, and its results are returned after evaluation for the current time step.

The statement of the expression could be as simple as a comparison between a property of an object and a reference value (e.g., ObjectType.ObjectName.Property > 25) or as complex as multiple comparisons linked by Boolean operators (e.g., ObjectType1.ObjectName1.Property1 > 25 and ObjectType2.ObjectName2.Property2 <= 15 or ObjectType3.ObjectName3.Property3 <> 'OFF').

Table 1 shows an example where the value of a QSET event for a gas demand object is chosen based on the control mode of a control valve. If GCV.CV_1.CTRL=='OFF' returns True at time step t_N, the demand of the gas offtake CGS_02 for time step t_N+1 is set to 10 ksm³/h. If GCV.CV_1.CTRL<>'OFF' returns True, the demand of the gas offtake CGS_02 is set to 150 ksm³/h and a profile. Both conditional events start at the same time. The rule for evaluating the condition is the same, and it is set to DoIFTRUE. The two events are mutually exclusive (i.e., the control valve can be on or off, but not both at any time step) because only one can be logically true for each time step. Figure 1 shows the flow rate at the offtake point and the control mode of the control valve. Note how the last event of the example is overwriting the conditional events from 06:00 a.m. of day 6.

Table 1. Example of a condition setting an event based on another object’s binary time-dependent variable (i.e., the control mode). The first two events specify the condition. The third event adds a new state which overwrites the condition from 06:00 a.m. of day 06/02/2022.
Start Time	Object Name	Parameter	Evaluation	Condition	Profile	Value	Unit of Measure
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GCV.CV_1.CTRL=='OFF'`	-	10	[ksm³/h]
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GCV.CV_1.CTRL<>'OFF'`	IND	150	[ksm³/h]
06/02/2022 06:00	CGS_02	`QSET`	NONE	-	-	100	[ksm³/h]

Figure 1. Evolution of the flow rate at the offtake point CGS_02 conditional on the control mode status of the control valve CV_1.

Table 2 shows an example where the value of a QSET event for a gas demand object is chosen based on the value of the outlet pressure of a control valve. If GCV.CV_1.PO<29.5 returns True at time step t_N, the demand of the gas offtake CGS_02 for time step t_N+1 is set to 10 ksm³/h. If GCV.CV_1.PO>=29.5 returns True, the demand of the gas offtake CGS_02 is set to 150 ksm³/h and a profile. Both conditional events start at the same time. The rule for evaluating the condition is the same, and it is set to DoIFTRUE. The two events are mutually exclusive (i.e., the outlet pressure can be either lower or higher and equal to the threshold of 29 bar-g, but not both at any time step). Figure 2 shows the flow rate at the offtake point and the control mode of the control valve. Compared to the previous example, two spikes are indicating how during the period the control valve is off, the outlet pressure goes above the threshold, but only for one time step for each spike. As before, the last event of the example is overwriting the conditional events from 06:00 a.m. of day 6.

Table 2. Example of a condition setting an event based on another object’s continuous time-dependent variable (i.e., outlet pressure of GCV.CV_1).
Start Time	Object Name	Parameter	Evaluation	Condition	Profile	Value	Unit of Measure
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GCV.CV_1.PO<29.5`	-	25	[ksm³/h]
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GCV.CV_1.PO>=29.5`	IND	150	[ksm³/h]
06/02/2022 06:00	CGS_02	`QSET`	NONE	-	-	100	[ksm³/h]

Figure 2. Evolution of the flow rate at the offtake point CGS_02 conditional on the outlet pressure of the control valve CV_1.

Table 3 shows an example where the value of a QSET event for a gas demand object is set based on the pressure at the same object and two different operational regions. The regions define a partition of the admissible values for the pressure of the offtake point. As in other examples, all conditions are mutually exclusive binary events and are evaluated with the same DoIFTRUE rule. Figure 3 shows the flow rate and the pressure of the offtake CGS_02. The spike around 09:15 a.m. of February 2^nd is caused by an oscillation around the threshold of 24.5 bar-g for the pressure.

This last example shows how to define a condition on an object, starting a feedback loop and ending on the same object. The other two examples demonstrate creating a feedback loop starting on a different object from the one impacted.

Table 3. Example of a condition setting an event based on a continuous time-dependent variable (i.e., pressure) of the same object.
Start Time	Object Name	Parameter	Evaluation	Condition	Profile	Value	Unit of Measure
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GDEM.CGS_02.P<24.5`	-	100	[ksm³/h]
01/02/2022 09:00	CGS_02	`QSET`	DoIFTRUE	`GDEM.CGS_02.P>=24.5`	IND	150	[ksm³/h]
06/02/2022 06:00	CGS_02	`QSET`	NONE	-	-	160	[ksm³/h]

Figure 3. Evolution of the flow rate at the offtake point CGS_02 conditional on its pressure.

3. Different types of evaluation rules

SAInt applies conditions only when an "evaluation rule" is specified. The evaluation rule answers the question: "For how long do I need to apply the event based on the outcome of the condition?". By default, SAInt uses the evaluation rule NONE, implying that the expression will not be considered. Possible valid rules are:

`DoIFTRUE`	at each time step, from the time of the event, the expression is assessed, and if the evaluation returns a logical `TRUE` the event is applied.
`DoIFFALSE`	at each time step, from the time of the event, the expression is assessed, and if the evaluation returns a logical `FALSE` the event is applied.
`DoUntilTRUE`	at each time step, from the time of the event, the expression is assessed, and the event is applied if the expression is `TRUE`. The first time the expression returns `FALSE`, the event is disregarded.
`DoUntilFALSE`	at each time step, from the time of the event, the expression is assessed, and the event is applied if the expression is `FALSE`. The first time the expression returns `TRUE`, the event is disregarded.

The use of DoIFTRUE and DoIFFALSE is equivalent if the condition is logically inverted. A DoIFTRUE for a statement like ObjectType.ObjectName.Property > 25 is equivalent to DoIFFALSE with ObjectType.ObjectName.Property <= 25. The same holds for DoUntilTRUE and DoUntilFALSE.

When multiple conditions are added to a scenario, special care must be applied to avoid logical inconsistencies in the set of evaluation rules. SAInt does not check for logical errors.

4. Bounding conditions to the simulation time

In a simulation, the period during which a condition is evaluated is generally defined by the starting time of the event and the starting time of another event for the same object. It is possible to change this behavior by adding a "time-dependent expression" in the condition statement. The SAInt built-in function gtime allows retrieving the time (in hours) of the current time step and making comparisons with user-defined values.

Let’s change the last event of example 1 (Table 1) in the following way:

Start Time Object Name Parameter Evaluation Condition Profile Value Unit of Measure

Start Time	Object Name	Parameter	Evaluation	Condition	Profile	Value	Unit of Measure
06/02/2022 06:00	CGS_02	`QSET`	IfTRUE	gtime<=132	-	100	[ksm³/h]
06/02/2022 06:00	CGS_02	`QSET`	IfTRUE	gtime>132	-	50	[ksm³/h]

06/02/2022 06:00

CGS_02

QSET

IfTRUE

gtime<=132

100

[ksm³/h]

06/02/2022 06:00

CGS_02

QSET

IfTRUE

gtime>132

[ksm³/h]

Figure 4 shows the effect of the new conditions on the flow rate at the offtake point CGS_02. The two new mutually exclusive conditions are evaluated using the rule IfTRUE and a time-dependent expression where the current time step is compared to a threshold value of hour 18:00 (06:00 p.m.) of February 6. The numeric value 132 indicates 5 days and 12 after the beginning of the simulation. For the time interval from 06/02/2022 06:00 to 06/02/2022 18:00 the first condition is true. And from 06/02/2022 18:00 onward, only the second condition is true.

This example is equivalent to the case of having two simple events starting 06/02/2022 at 06:00 and 06/02/2022 at 18:00, respectively, with no conditions.

Figure 4. Evolution of the flow rate at the offtake point CGS_02 based on the set of conditions of example 1 and using the function gtime.