Objects

An object is a unique entity in a network model. Objects span from simple building blocks up to full network instances. They can be subdivided into different classes, each representing a type, such as nodes, branches, externals, networks, subs, zones, and groups. The most fundamental object types are nodes, branches, and externals, as they are the fundamental blocks for building a network model.

SAInt has a certain number of "base objects" classes, which describe real-world physical elements and facilities of a gas, electric, or coupled network in mathematical terms. A base object is characterized by a set of properties and by the way it relates to other objects of a different type. SAInt makes a distinction between "child" and "parent" objects. A base object whose existence depends on another type of base object is considered its child. A base object encompassing or containing other types of base objects is referred to as a parent. In this way, it is possible to organize all base objects in a defined hierarchy of parent and child objects. A full list of base objects is provided in the sections "electric objects", "gas objects", "thermal objects" and "hub objects".

A network is also an object. However, a network object (e.g., ENET,GNET or TNET) is unique since only one for each type of system can exist in a model.

A model prepared using a version of SAInt other than the latest (i.e., 3.4.x) will be automatically backed up during the opening process. The backup files can be found in the 'Backup' folder and can be opened in the older version of SAInt, if required.

Every object in a network model is uniquely identified by its object type code (e.g., ENO for an electric node, GBR for a gas branch, or TXT for a generic thermal external) and user-defined name. The combination of "object type code and name separated by a dot symbol" is an object identifier (Object-ID). For instance, "ENO.PARIS" is the unique object ID of an electric node ENO named "PARIS".

The object name and identifier have the following restrictions:

  • The object name must start with a letter.

  • The object name can only contain alpha-numeric characters (letters and numbers). The only exception and allowed non-alpha-numeric character is the underscore "_".

  • The object identifier must be unique. Objects (externals) cannot have the same name, even if they are of different object type.

Every object has properties called Alias and Info which can hold alternative names and additional information about an object without any character restrictions.

1. Network objects

An energy network in SAInt is described, in abstract terms, by using a mathematical graph. In mathematics, a "graph" is a set of objects, called nodes or vertices, which are related in pairs, called edges or links. Both vertices and edges may have additional attributes contributing to the properties and behavior of the network.

The following sections describe the main objects in SAInt modeling the vertices and the links of a graph.

1.1. Node

A node represents a — physical or virtual — location within a model where energy (gas, electricity, heat, etc.) can be injected into or extracted from the network. A node is the equivalent of a vertex in a graph.

The current release of SAInt has three main object type codes for indicating a node. An electric node is represented by the code ENO. A gas node is represented by the code GNO. A thermal node is represented by the code TNO. The ID TNO.N1 indicates a thermal node named 'N1'.

1.2. Branch

A branch is a directed connection between a pair of nodes. One of the two nodes is referred to as FromNode and the other as ToNode. The flow direction in a branch is positive if the flow goes from the FromNode to the ToNode. Otherwise, the direction is negative. A branch models facilities with an inlet, an outlet, and a flow direction. A branch is the equivalent of a link in a graph.

The current release of SAInt has many different types of branches as, for example, an electric line LI, an electric transformers TRF, a gas pipeline GPI, a gas compressor station GCS, or a thermal pipe TPI.

1.3. External

An external represents an object directly connected to a node, extracting or injecting energy at that node. An external is used to model demand, supply, and storage in a network. A node can have multiple externals linked. An external represents a set of special attributes of a vertex of a graph. Such attributes describe the behavior of the vertex with respect to inflow or outflow.

The sign/direction convention of the energy flow exchange at a node is:

  • Positive (+) if energy is injected or supplied to the node

  • Negative (-) if energy is extracted or consumed from the node.

The current release of SAInt has many different types of externals like, for example, an electric demand EDEM, a gas supplies GSUP, a thermal heat demand HDEM, a LNG terminal LNG, or a generic power generator XGEN.

2. Properties

The properties describe the unique characteristics and physical attributes of an object in SAInt. Every property of an object has a specific name and unit type. Each property has three different ways its name can be used for. We have:

DisplayName

it is the name used and displayed in the property editor and context menu.

Extension

it is the abbreviation used in expressions and when importing and exporting data.

PropertyName

it is the name used in the source code and SAInt-GUI-Help.chm document.

The combination of object-ID and property extension separated by a dot '.' character can be used to retrieve the property value of an object. The extension is an abbreviation representing the input or output property of an object. The set of properties and extensions is based on the object type. The complete list of properties for each object type is available in the "Lexicon", which can be found in .\SAInt-v3\Documents, and on the following pages: "electric objects", "gas objects", "thermal objects" and "hub objects".

The property value of an object can be obtained through the command window, script editor or API using the following expression:

ObjectType.ObjectName.Extension

Alternatively, the user can specify the units and specific scenario time or elapsed hours after the start of the scenario (for time-dependent properties) to retrieve the value with the following expression:

`ObjectType.ObjectName.Extension.[Unit].(Time)`s

The Unit and Time definitions are optional. If no Unit information is specified then the property value will be displayed in the DisplayUnit for the corresponding UnitType, which can be set in the unit tab of the Settings Window. If no Time information is specified, then the property value is displayed for the current DisplayTime.

The properties of an object can be classified into the following groups:

Network properties

  • NETWORK read-only and time-independent network properties;

  • NETWORKINPUT editable and time-independent network input properties;

Scenario event properties

  • EVENTDEFAULT editable and time-independent scenario event default properties;

  • EVENTVALUE read-only and time-dependent scenario event value properties;

  • DERIVEDEVENTVALUE read-only, time-dependent, and derived scenario event value properties;

Scenario result properties

  • BASERESULT read-only and time-dependent base result properties;

  • DERIVEDRESULT read-only, time-dependent, and derived scenario result properties;

Some properties may be applicable only to specific scenario types. In SAInt, the information box on the bottom part of the property editor allows users to identify which properties are applied to a specific scenario type.

2.1. Network properties

The network properties define the general attributes and static parameters of an object.

General properties, which are common to every object type, are:

ObjectType (ObjType)

this property defines the classification of an object within the network model.

UniqueID (UID)

an automatically generated unique identifier used by SAInt to internally identify each object.

NetworkType (NetType)

this property defines the energy carrier used by the network model.

Name

this property defines the name of the object. SAInt proposes a default name, but the user can personalize the value.

Alias

Any alternative name of the object.

ObjectID (ID)

Refers to the combination of object type and name to identify the object "ObjectType.ObjectName".

Info

Any additional information related to the object.

UID are generated every time a model is created.

For example, if the user creates two models using the same import template, the scenario files *.*sce and solutions *.*sol are not interchangeable because the UID of the objects in both *.*net files are not the same.

Each object type has, also, specific time-independent properties. These object-specific properties are defined as 'static' since they should not be modified once the network model has been built. For example, the elevation of a node or the length of a gas pipeline is an object-specific property.

2.2. Scenario event properties

Scenario event properties define time-dependent object properties. These properties may change at different moments during the execution of a scenario by using scenario events and scenario profiles. In each section in this documentation dealing with objects, the user can find a part titled "Event" that shows the list of events available for the selected object.

Event Parameter Type

The events are classified by Parameter Type, the following table presents a short description of the available parameters:

Parameter Type
Parameter Description

IniSetting

Initial simulation setting used by the solver, e.g., REVON or HTON.

ControlSetPoint

Prescribed configuration, i.e., control set, which is under the solver’s control, e.g., POSET.

SetPoint

Prescribed value for an object’s property in the scenario, not under the solver’s control, e.g., PFSET.

StorageSetPoint

Prescribed value for a storage object’s property, e.g., VOLSET or SOCSET.

State

Assigns the operation state of the object, like ON or OFF.

IniState

Initial operation State of the object, like ONINI or OFINI.

Constraint

Defines the upper or lower limit of the variable, e.g., PMIN or PMAX.

PenaltyPrice

Assigns a cost for violating the constraint or set point, like PMAXPRC or VOLSETPRC.

Price

Assigns a price to an object’s variable, e.g., VOMPrice.

Reference

Assigns a reference value to an object property used for comparing or visualization purposes, e.g., PREF.

Coefficient

Prescribes a value to coefficients associated with a generator cost function or electric constraints, e.g, C0 or Coeff.

Efficiency

Assigns to an object property an efficiency value, like EFFH.

Ambient

Defines ambient conditions, e.g., TAMB.

Default scenario event properties

The default scenario event properties are preset values set by SAInt or the user for a specific object parameter in the network file. These properties have a prefix Def in their DisplayName or a suffix DEF in their extension. For example, the default maximum active power of an electric branch (EBR) display name is DefMaxActivePower, while the extension is PMAXDEF.

Some objects may have object-specific properties which look like a default scenario event property. But they cannot be modified with an event value property since they describe the physical static parameters of the object. For example, The impedance properties RRDEF, XXDEF, BBDEF, and GGDEF of electric branches (EBR, LI, TRF).

Event value properties

Event value properties are used to describe the behavior of an object property at a specific scenario time. They are created using scenario events in the loaded scenario file. For time-dependent object parameters, scenario profiles can be used to dynamically change the event value during the execution of a scenario. For example, consider a gas simulation starting at 6 a.m. on day one with a supply point "SUP01" set to operate at a certain pressure level. The user can change this property by setting an event like GSUP.SUP01.PSET to a different pressure level and specify the time of this new event.

When an event value property is assigned to an object property in a scenario file, the event value overwrites the default scenario event property value set in the network file. For example, if the user sets a PMAXDEF of 30 MW for an electric branch and a PMAX event value of 40 [MW] is set in the scenario, the PMAX considered in the simulation is 40 [MW].

2.3. Scenario result properties

The scenario results properties return the results for an executed scenario. Results are separated into two categories: base result properties and derived result properties.

In case the execution of a scenario fails before the scenario end time, the results can be accessed until the time step of the failure.

Base result properties

Base result properties represent the computed values of the variables for each object of the mathematical model and are saved in the state and/or solution files. For example, the active power (P) of a wind generator is a base result in a DCUCOPF scenario.

A property does not necessarily have to be a base result for all scenario types.

Derived result properties

Derived result properties are properties that return results calculated internally by SAInt from the base result properties of the scenario. These properties are not saved in state or solution files. For example, the power not served (PNS) of a wind generator is a derived result in a DCUCOPF scenario.

Retrieving derived results for a large model ENET.PPV, ENET.PFGEN, etc.), may require some time depending on the size of the model and the settings for the Scenario properties ChartStartTime, ChartEndTime, and ChartTimeStep.

SAInt links events and properties to objects using the UID as a key.

This fact is crucial because a user can change, for example, the Name of an object, but all the *.*net properties, *.*sce events, and *.*sol results will not be affected.