Template Files

A network template file is a multi-sheet Excel spreadsheet file. It allows designing a network by specifying all its characteristics, the full list of objects to include, and their properties. A network is independent of the scenario type implemented in a simulation, and therefore there is no scenario-related information in the template. Figure 1 shows the four templates available in the directory Network of the folder DataImport. They are the template for an electric network (*.ENET, middle-top), the template for a gas network (*.GNET, middle), the template for a thermal network (*.TNET, middle-bottom), and the template for a hub system (*.HUBS, bottom).

The structure of a template is the same for all types of networks. The first two sheets report the list of extensions with displayed names and descriptions (the INFO sheet) and the list of units of measurement with descriptions and aliases used in all other sheets (the UNITINFO). Then, there is a set of sheets for the containers. The sheet name depends on the type of system and its content on the type of object. There are four sheets: a network sheet, a subset sheet, a zone sheet, and a group sheet. The remaining template sheets cover the objects of the specific network type. There is a sheet for nodes and another for each type of supported branch. Finally, there could be sheets covering other aspects of a network like gas quality in gas systems or ancillary services in electric systems. The POLY sheet at the end represents vertices in branches describing bending lines and turns.

Except for the first two information sheets, all the remaining ones share a common structure: a header row and data rows. The data rows are empty as the user is supposed to fill in the data. The header row reports the column’s name based on a predefined format: object "extension", the unit of measurement, the symbol =, and a numerical/Boolean value to be used as reference. Default units and values are used if only the extension is reported. When it comes to the extension Name only the name of the object is required.

SAInt automatically checks the header. If the header format is not respected, it returns an error for the import process. The user is informed to take action.

Custom column headers and sheets are allowed in the network import template. SAInt will not take them into account during the import procedure. The details of what has been taken into consideration and what not is logged for the user.

The file Template_ENET.xlsx allows the creation of a network import file of an electric network. The file Template_GNET.xlsx allows allows the creation of a network import file of a gas network. The file Template_TNET.xlsx allows allows the creation of a network import file of a thermal network. The file Template_HUBS.xlsx allows allows the creation of a network import file representing an HUB system. An HUB system combines different types of networks, and it defines which objects are coupled (i.e., using HUB objects) between the network types. A HUB system requires to create — at least — two separate networks (e.g., an *.ENET and a *.GNET), and after specifying the HUB objects.

For a detailed description of the network’s objects and their properties, please check the section "Electric Objects", the section "Gas Objects", the section "Thermal Objects", and the section "Hub Objects".

Profiles can be imported into SAInt by single-sheet format files either in Excel or in text format. The Excel file Template_Profile_Import.xlsx is, probably, the easiest options, because it constraints the user to follow a clear predefined layout, and quickly organize the data in a spreadsheet. Figure 1 describes how the data for three different types of profiles must be organized in two sheets named PRF and PRFDATA.

The example shows three hourly profiles (see the PRFTIME parameter set to [h]), called PROFILE1, PROFILE2, and PROFILE3 (see the ProfileName property). All general properties of a profile are reported in PRF. PROFILE1 is a deterministic profile, with a timestep of one hour, a cubic interpolation between steps, and its duration is set to periodic. The Info property can hold any additional piece of information deemed useful by the user. For this profile, the property DistributionType is not relevant and set to UNIFORM to showcase the three most common distribution types in SAInt (i.e., uniform, normal, and exponential distribution). The actual values of a profile are reported in PRFDATA. There profiles are organized in columns, starting with the name in square brackets in the first cell, followed by the label Mean or Deviation, and the numeric values of the profile steps. The label Mean is used for all types of profiles, while Deviation must be specified only for stochastic profile types.

Alternatively, a text file template can be used. The structure of the template mimics the one in an Excel file. The file starts with the information of the PRF sheet, and it reports sequentially the values of each profile. See the following example. Please, remember that cells with any value are separated by a tab.

Scenario events can be imported into SAInt by single-sheet format files either in Excel or in text format (e.g., text TAB delimited *.txt files, or text comma separated *.csv files). In the Scenario directory of the DataImport the user can find the Excel templates. Examples of the other formats can be generated by exporting a scenario created in SAInt and checking the structure. The Excel template is the preferred solution as it is very easy to use, adapt, and process.

A scenario events file allows creating a list of events for any object in the active network and defining its relevant properties. The available events depend on the type of network considered.

The Excel file Template_ESCE.xlsx is designed to create an electric scenario. Figure 3 shows an empty template. The same ESCE is used for all the electric scenario types (SteadyState, QuasiDynamic, and Dynamic). The information needed is:

The Excel file Template_GSCE.xlsx is designed to create a gas scenario. The same GSCE is used for all the gas scenario types (SteadyGas, DynamicGas). Its content is the same as the one for an electric scenario.

The fastest and most efficient way to import in SAInt data available in a geographic information system is to use the templates in shapefile format.

Templates for pipelines and externals in gas networks are provided in shapefile format in the directory Shapefile\Gas in DataImport. The files Gas_Pipelines.shp, Gas_Pipelines.dbf, and Gas_Pipelines.shx constitute a shapefile container for pipeline objects. The files Gas_Nodes_XXX.shp, Gas_Nodes_XXX.dbf, and Gas_Nodes_XXX.shx constitute a shapefile container for externals, and all other linear objects. A shapefile container is provided for each different object in a gas network. The _XXX part in the name indicates the type of object, like, for example, Gas_Nodes_GCS.shp stands for the compressor stations (GCS).

Templates for electric lines, transformers, and externals in electric networks are provided in shapefile format in the directory Shapefile\Electric in DataImport. The files Electric_lines.shp, Electric_lines.dbf, and Electric_lines.shx constitute a shapefile container for electric line objects. The files Electric_Nodes_XXX.shp, Electric_Nodes_XXX.dbf, and Electric_Nodes_XXX.shx constitute a shapefile container for nodes and externals, and all other linear objects. A shapefile container is provided for each different object in an electric network. The _XXX part in the name indicates the type of object, like, for example, Electric_Nodes_EDEM.shp stands for externals for an electric demand (EDEM).

Templates for pipelines and externals in thermal networks are provided in shapefile format in the directory Shapefile\Thermal in DataImport. The files Thermal_Pipelines.shp, Thermal_Pipelines.dbf, and Thermal_Pipelines.shx constitute a shapefile container for pipeline objects. The files Thermal_Nodes_XXX.shp, Thermal_Nodes_XXX.dbf, and Thermal_Nodes_XXX.shx constitute a shapefile container for externals. A shapefile container is provided for each different object in a thermal network. The _XXX part in the name indicates the type of object, like, for example, Thermal_Nodes_HSUP.shp stands for the heat supply externals (HSUP).

The templates contain mock examples for all different types of branches, externals, and their properties. The column’s name in the attribute table matches the corresponding property name in SAInt. In a few cases, the name has been shortened due to the limitation to 10 characters of the DBF format. The templates have no coordinate system defined. Each numerical property in SAInt is associated with two columns in the DBF table of the shapefile. The first column is for the numeric value. The second column allows the user to record the unit of measure used to represent the numerical value. The name of this second column ends with 'u' for the unit. SAInt does not use this column.

For a step-by-step description of how to import generic shapefiles in SAInt refer to the How-To "Import Network Data in Shapefile Format".

Wind turbine power curves (WTPC) can be imported into SAInt by single-sheet text format files. The WTPC import file can only be imported if an electric network is active in SAInt. These templates are saved in .\DataImport\WindTurbinePowerCurve. A template can be easily customized for models that are not present in SAInt’s database.

A template is composed of three sections: the [UNIT] section, the [DEF]`section, and the `[DATA] section. In the [UNIT] section, the user lists the variables of the curve and the associated units of measures. In the [DEF]`section, the user specify which class of mathematical relationship links the variables (generally a `Linear class). Finally, in the [DATA] section, the user lists the values of the variables for building the relationship.

Multiple curves could be saved in the same text file. Each curve must have its row in the [DEF] section, and values in the [DATA] section, with the name of the curve next to the label [DATA]. Please, note that in the following example, the sequence "->" represents a TAB. A line starting with % indicates a comment.

Fuel consumption curves (FCC) can be imported into SAInt by single-sheet text format files. The FCC import file can only be imported if an electric network is active in SAInt. These templates are saved in .\DataImport\FuelConsumptionCurve. The user can easily customize the template to model new curves.

A template is composed of one main section and possible comment lines. The main section starts with the [DATA] filed followed by the name of the curve. Spaces must be avoided in names. The following line reports the part where units of measurement are defined for power and fuel consumption between square brackets. The last part of the section is defining couples of values for describing the curve. The first and last couple must start with PMIN and PMAX. In this way the curve has clear boundaries.

Multiple curves could be saved in the same text file. Each curve must have its [DATA] section and values. Please, note that in the following example, the sequence "->" represents a TAB. A line starting with % indicates a comment.

In the directory .\DataImport\Quality the user can find two other resources. The file DataProviderURL.txt lists the URL of the weather resource database provider accessible by SAInt. See "Integrating Weather Resource Data" for a detailed description of the topic.

The gas quality template file is a multi-sheet format file either in Excel or in text file format (e.g., text TAb delimited *.txt files, or text comma separated *.csv files). The Excel file template is the preferred solution, and it is available with the file GasQualityImport.xlsx in .\DataImport\Others. The text file template is the file GasQualityImport.txt.

Its structure mimics closely the one of an Excel template. The [GCMP] section is for gas components, and it starts with a header line describing which properties and units of measure, followed by a new row for each component with the necessary data. The [GQUAL] section is for gas quality streams, and it starts with a header line describing which properties and units of measure, followed by a new row for each gas quality with the necessary data. The last section is [GCUS], where the compositional data for each gas stream are provided. Finally, the user can specify the units of measure used in the template either by introducing a dedicated section [UNIT] or by indicating the units in the header row. If both options are used, the units specified in the header row is the one used.

Please, note that when a property is calculated by SAInt or is derived by the build-in SAInt database, its place in the template is empty. In the following example, we have one gas component (i.e., neon) and three gas qualities (i.e., default, Groningen and Qatar). Units of measure as specified in both the [UNIT] section and in the header row. For TC values will be interpreted as Celsius degrees. The sequence "->" represents a TAB. A line starting with % indicates a comment.

In the directory .\DataImport\Template, the user can find the Python script run_cem.py, which can be personalized to run a CEM optimization from the SAInt API and the folder Input collecting comma-separated files (CSV) for specifying different aspects of a CEM model. The CSV files cover:

In the directory .\DataImport\Others, the user can find the file DataProviderURL.txt. This file lists the URL of the weather resource database provider accessible by SAInt. See "Integrating Weather Resource Data" for a detailed description of the topic.