Data reference

Warning

This reference is work in progress.

FLEDGE scenarios are defined through CSV files, where each CSV file represents a table as defined below (the file name is interpreted as the table name). Internally, FLEDGE loads all CSV files into a local SQLITE database for more convenient processing. The default location for FLEDGE scenario definitions is in the data directory in the repository and all CSV files in the data directory are automatically loaded into the database. The CSV files may be structured into sub-directories, but all files are eventually combined into the same database. Hence, all type / element identifiers must be unique across all scenario definitions.

Scenario data

scenarios

Scenario definition.

Column	Unit	Description
scenario_name		Unique scenario identifier.
electric_grid_name		Electric grid identifier as defined electric grids
thermal_grid_name		Thermal grid identifier as defined thermal grids
parameter_set		Parameter set identifier as defined in parameters
price_type		Type identifier as defined in price_timeseries
price_sensitivity_coefficient	$/kWh²	Price sensitivity coefficient for the quadratic cost terms of DERs / grids. Optional column, which defaults to 0 if not explicitly defined.
electric_grid_operation_limit_type		Operation limit type as defined in electric_grid_operation_limit_types
thermal_grid_operation_limit_type		Type identifier as defined in thermal_grid_operation_limit_types
timestep_start		Start timestep in format yyyy-mm-ddTHH:MM:SS (according to ISO 8601).
timestep_end		End timestep in format yyyy-mm-ddTHH:MM:SS (according to ISO 8601).
timestep_interval		Time interval in format HH:MM:SS

parameters

In all tables, a parameter_name string can be used to define numerical parameters in place of numerical values (identifiers or string values cannot be replaced with parameters). During model setup, those strings will be parsed from the parameters table to obtain the corresponding numerical values.

Column	Unit	Description
parameter_set		Parameter set identifier.
parameter_name		Unique parameter identifier (must only be unique within the associated parameter set).
parameter_value	-	Parameter value.

price_timeseries

Price timeseries.

Column	Unit	Description
price_type		Unique type identifier.
time		Timestamp according to ISO 8601.
price_value	$/kWh	Price value. Currently, prices / costs are assumed to be in SGD.

Electric grid data

electric_grids

Electric grid definition.

Column	Unit	Description
electric_grid_name		Unique electric grid identifier.
source_node_name		Source node name as defined in electric_grid_nodes
base_frequency	Hz	Nominal grid frequency.
is_single_phase_equivalent		Single-phase-equivalent modelling flag¹. If 0, electric grid is modelled as multi-phase system. If 1, electric grid is modelled as single-phase-equivalent of a three-phase balanced system. Optional column, which defaults to 0 if not explicitly defined.

¹ If single-phase-equivalent modelling is used, all nodes, lines, transformers and DERs must be defined as single-phase elements, i.e., these elements should be connected only to phase 1. However, all power values (DER active / reactive power, transformer apparent power) must be defined as total three-phase power.

electric_grid_ders

Distributed energy resources (DERs) in the electric grid. Can define both loads (negative power) and generations (positive power). The corresponding DER models are defined in der_models. The selection of DER types will be extended in the future.

Column	Unit	Description
electric_grid_name		Electric grid identifier as defined in electric_grids.
der_name		Unique DER identifier (must only be unique within the associated electric grid).
der_type		DER type selector, which determines the type of DER model to be used. Choices: fixed_load, flexible_load, fixed_ev_charger, flexible_building, fixed_generator, flexible_generator, cooling_plant.
der_model_name		DER model identifier as defined in der_models. For flexible_building, this defines the CoBMo the scenario name.
node_name		Node identifier as defined in electric_grid_nodes.
is_phase_1_connected		Selector for connection at phase 1. Choices: 0 (connected), 1 (not connected).
is_phase_2_connected		Selector for connection at phase 2. Choices: 0 (connected), 1 (not connected).
is_phase_3_connected		Selector for connection at phase 3. Choices: 0 (connected), 1 (not connected).
connection		Selector for Wye / Delta connection. Choices: wye, delta.
active_power_nominal	W	Nominal active power, where loads are negative and generations are positive.
reactive_power_nominal	VAr	Nominal reactive power, where loads are negative and generations are positive.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

electric_grid_line_types

Electric line type definitions are split into electric_grid_line_types for the general type definition and electric_grid_line_types_matrices for the definition of electric characteristics.

Column	Unit	Description
line_type		Unique type identifier.
n_phases	-	Number of phases.
maximum_current	A	Maximum permissible current (thermal line limit).

electric_grid_line_types_matrices

Electric line characteristics are defined in terms of element property matrices. Note that the matrices are expected to be symmetric and therefore only the lower triangular matrix should be defined. The matrices are defined element-wise (indexed by row / column pairs), to allow definition of single-phase line types alongside multi-phase line types.

Column	Unit	Description
line_type		Line type identifier as defined in electric_grid_line_types.
row		Element matrix row number (first row is 1).
col		Element matrix column number (first column is 1).
resistance	Ω/km	Series resistance matrix entry.
reactance	Ω/km	Series reactance matrix entry.
capacitance	nF/km	Shunt capacitance matrix entry.

electric_grid_lines

Electric grid lines.

Column	Unit	Description
electric_grid_name		Electric grid identifier as defined in electric_grids
line_name		Unique line identifier (must only be unique within the associated electric grid).
line_type		Line type identifier as defined in electric_grid_line_types.
node_1_name		Start node identifier as defined in electric_grid_nodes
node_2_name		End node identifier as defined in electric_grid_nodes
is_phase_1_connected		Selector for connection at phase 1. Choices: 0 (connected), 1 (not connected).
is_phase_2_connected		Selector for connection at phase 2. Choices: 0 (connected), 1 (not connected).
is_phase_3_connected		Selector for connection at phase 3. Choices: 0 (connected), 1 (not connected).
length	km	Line length.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

electric_grid_nodes

Electric grid nodes.

Column	Unit	Description
electric_grid_name		Electric grid identifier as defined in electric_grids
node_name		Unique node identifier (must only be unique within the associated electric grid).
is_phase_1_connected		Selector for connection at phase 1. Choices: 0 (connected), 1 (not connected).
is_phase_2_connected		Selector for connection at phase 2. Choices: 0 (connected), 1 (not connected).
is_phase_3_connected		Selector for connection at phase 3. Choices: 0 (connected), 1 (not connected).
voltage	V	Nominal voltage.
latitude		Latitude.
longitude		Longitude.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

electric_grid_operation_limit_types

Operation limit type definition for the electric grid. This information is utilized for the definition of the operational constraints in an optimal operation problem.

Column	Unit	Description
electric_grid_operation_limit_type		Unique type identifier.
voltage_per_unit_minimum	-	Minimum voltage in per unit of the nominal voltage.
voltage_per_unit_maximum	-	Maximum voltage in per unit of the nominal voltage.
branch_flow_per_unit_maximum	-	Maximum branch flow in per unit of the branch flow at nominal loading conditions.

electric_grid_transformer_types

Transformer type characteristics.

Column	Unit	Description
transformer_type		Unique type identifier.
resistance_percentage	-	Resistance percentage.
reactance_percentage	-	Reactance percentage.
tap_maximum_voltage_per_unit	-	Maximum secondary side tap position. (Currently not used.)
tap_minimum_voltage_per_unit	-	Minimum secondary side tap position. (Currently not used.)

electric_grid_transformers

Electric grid transformers, which are limited to transformers with two windings, where the same number of phases is connected at each winding.

Column	Unit	Description
electric_grid_name		Electric grid identifier as defined in electric_grids
transformer_name		Unique transformer identifier (must only be unique within the associated electric grid).
transformer_type		Transformer type identifier as defined in electric_grid_transformer_types
node_1_name		Primary side node name as defined in electric_grid_nodes
node_2_name		Secondary side node name as defined in electric_grid_nodes
is_phase_1_connected		Selector for connection at phase 1. Choices: 0 (connected), 1 (not connected).
is_phase_2_connected		Selector for connection at phase 2. Choices: 0 (connected), 1 (not connected).
is_phase_3_connected		Selector for connection at phase 3. Choices: 0 (connected), 1 (not connected).
connection		Selector for Wye / Delta connection. Choices: wye, delta. Note that Wye-connected windings are assumed to be grounded.
apparent_power	VA	Nominal apparent power loading.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

Thermal grid data

thermal_grids

Thermal grid definition.

Column	Unit	Description
thermal_grid_name		Unique thermal grid identifier.
source_node_name		Source node name as defined in thermal_grid_nodes.
distribution_pump_efficiency	-	Pump efficiency (pump power / electric power) of the secondary side pumps, i.e. the pumps in the distribution system / thermal grid.
energy_transfer_station_head_loss	m	Pump pressure head loss in the energy transfer station at each DER.
enthalpy_difference_distribution_water	J/kg	Enthalpy difference between supply and return side of the distribution water, i.e. the water flowing to the thermal grid.
water_density	kg/m³	Density of the distribution water.
water_kinematic_viscosity	m²/s	Kinematic viscosity of the distribution water.
plant_type		Thermal supply plant type. Currently only cooling_plant is supported.
plant_model_name		Plant model identifier. If plant type cooling_plant, as defined in der_cooling_plants.

thermal_grid_ders

Distributed energy resources (DERs) in the thermal grid. Can define both loads (negative power) and generations (positive power). The corresponding DER models are defined in der_models. The selection of DER types will be extended in the future.

Column	Unit	Description
thermal_grid_name		Thermal grid identifier as defined in thermal_grids.
der_name		Unique DER identifier (must only be unique within the associated thermal grid).
node_name		Node identifier as defined in thermal_grid_nodes.
der_type		DER type selector, which determines the type of DER model to be used. Choices: flexible_building, fixed_generator, flexible_generator, cooling_plant.
der_model_name		DER model identifier as defined in der_models. For flexible_building, this defines the CoBMo the scenario name.
thermal_power_nominal	W	Nominal thermal power, where loads are negative and generations are positive.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

thermal_grid_line_types

Thermal line types for defining pipe characteristics.

Column	Unit	Description
line_type		Unique type identifier.
diameter	m	Pipe diameter.
absolute_roughness	mm	Absolute roughness of the pipe.
maximum_velocity	m/s	Nominal maximum pipe velocity.

thermal_grid_lines

Thermal grid line (pipe) definitions. The definition only includes the supply side piping, as the return side is assumed be symmetric.

Column	Unit	Description
thermal_grid_name		Thermal grid identifier as defined in thermal_grids.
line_name		Unique line identifier (must only be unique within the associated thermal grid).
line_type		Line type identifier as defined in thermal_grid_line_types.
node_1_name		Start node identifier as defined in thermal_grid_nodes
node_2_name		End node identifier as defined in thermal_grid_nodes.
length	km	Line length.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

thermal_grid_nodes

Thermal grid nodes.

Column	Unit	Description
thermal_grid_name		Thermal grid identifier as defined in thermal_grids.
node_name		Unique node identifier (must only be unique within the associated thermal grid).
latitude		Latitude.
longitude		Longitude.
in_service		In-service selector. Not-in-service grid elements are ignored and not loaded into the model. Choices: 1 (in service) or 0 (not in service). Optional column, which defaults to 1 if not explicitly defined.

thermal_grid_operation_limit_types

Operation limit type definition for the thermal grid. This information is utilized for the definition of the operational constraints in an optimal operation problem. Note that thermal line limits are currently defined in per unit of the nominal thermal power solution, i.e., the thermal power flow solution for nominal loading conditions as defined in thermal_grid_ders, but this should be changed in future.

Column	Unit	Description
thermal_grid_operation_limit_type		Unique type identifier.
node_head_per_unit_maximum	-	Maximum node head, in per unit of the nominal thermal power solution.
pipe_flow_per_unit_maximum	-	Maximum pipe / branch flow, in per unit of the nominal thermal power solution.

Distributed energy resource (DER) data

der_models

DER model parameter definitions. This table incorporates the definition of various DER types, which have different characteristics and require a different subset of the columns. See below for a detailed description of each DER type.

Column	Unit	Description
der_type		DER type selector. Choices: fixed_load, flexible_load, fixed_generator, flexible_generator, fixed_ev_charger, cooling_plant, storage. Note: flexible_buildings cannot be defined here, because it is obtained from the CoBMo submodule directly.
der_model_name		Unique DER model identifier (must only be unique within the associated DER type).
definition_type		Definition type selector, because most DER types require either additional timeseries / schedule definition¹ or other supplementary parameter definitions from either of the tables der_timeseries, der_schedules or der_cooling_plants. Choices: timeseries (Defines timeseries of absolute values².) schedule (Defines schedule of absolute values².), timeseries_per_unit (Define timeseries of per unit values².), schedule_per_unit (Defines schedule of per unit values².), cooling_plant (Defines cooling plant.)
definition_name		Definition identifier, which corresponds to definition_name in either der_timeseries, der_schedules or der_cooling_plants. If definition_type is timeseries or timeseries_per_unit: defined in der_timeseries; if definition_type is schedule or schedule_per_unit: defined in der_schedules; if definition_type is cooling_plant: defined in der_cooling_plants.
power_per_unit_minimum	-	Minimum permitted power (load or generation) in per unit of the nominal power.
power_per_unit_maximum	-	Maximum permitted power (load or generation) in per unit of the nominal power.
power_factor_minimum		Minimum permitted power factor. Currently not used.
power_factor_maximum		Maximum permitted power factor. Currently not used.
energy_storage_capacity_per_unit	h	Energy storage capacity in per unit of the nominal active or thermal power. For example, nominal power of 1000 W and per-unit energy storage capacity of 3 h correspond to 3000 Wh energy storage capacity.
charging_efficiency	-	Energy storage charging efficiency factor.
self_discharge_rate	1/h	Energy storage self discharge rate.
marginal_cost	$/kWh	Marginal cost of power generation. Currently, prices / costs are assumed to be in SGD.

For most DER types, the der_models table is supplemented by timeseries / schedule definitions in the tables der_timeseries / der_schedules or supplementary parameter definitions in der_cooling_plants based on the columns definition_type / definition_name. Furthermore, each DER type relies on a different subset of columns / parameters in der_models. The table below outlines the required supplementary definitions for as well as the required columns for each DER type:

DER type	Description	Required columns	Required supplementary definitions
fixed_load	Fixed load, following a fixed demand timeseries.	definition_type, definition_name	Timeseries / schedule¹ for nominal active / reactive / thermal power².
flexible_load	Flexible load, following a demand timeseries, but able shift a share of its nominal load, limited by its energy storage capacity.	definition_type, definition_name, power_per_unit_minimum, power_per_unit_maximum, energy_storage_capacity_per_unit	Timeseries / schedule¹ for nominal active / reactive / thermal power².
fixed_generator	Fixed generator, following a fixed generation timeseries.	definition_type, definition_name, marginal_cost	Timeseries / schedule¹ for nominal active / reactive / thermal power².
flexible_generator	Flexible generator, dispatchable within given limits and based on a generation timeseries.	definition_type, definition_name, power_per_unit_minimum, power_per_unit_maximum, marginal_cost	Timeseries / schedule¹ for nominal active / reactive / thermal power².
fixed_ev_charger	Fixed EV charger, following a fixed demand timeseries.	definition_type, definition_name	Timeseries / schedule¹ for nominal active / reactive / thermal power².
cooling_plant	Cooling plant, converts electric power to thermal power, dispatchable with nominal power limits.	definition_type, definition_name	Cooling plant parameters according to der_cooling_plants.
storage	Energy storage, can charge / discharge within given limits and based on its energy storage capacity.	power_per_unit_minimum, power_per_unit_maximum, energy_storage_capacity_per_unit, charging_efficiency, self_discharge_rate	N.A.

The selection of DER types will be extended in the future. Note that the DER type flexible_buildings is not defined here, instead the model definition is obtained from the Control-oriented Building Model (CoBMo) submodule.

Not all DER types can be connected to all grid types, e.g. fixed_ev_charger is only available in the electric grid. Refer to electric_grid_ders / thermal_grid_ders to check which DER types can be connected respectively.

¹ For DER types which require the definition of timeseries values, these can be defined either directly as a timeseries or as a schedule, where the latter describes recurring schedules based on weekday / time of day (see der_schedules).

² Active / reactive / thermal power values can be defined as absolute values or in per unit values. Per unit values are assumed to be in per unit of the nominal active / reactive power as defined electric_grid_ders / thermal_grid_ders. Note that the sign of the active / reactive / thermal power values in the timeseries / schedule definition are ignored and superseded by the sign of the nominal active / reactive / thermal power value as defined in electric_grid_ders / thermal_grid_ders, where positive values are interpreted as generation and negative values as consumption. Additionally, note that der_timeseries / der_schedules only define a single power value for each timestep. Thus, for electric DERs the active power is derived directly based on the value in der_timeseries / der_schedules and the reactive power is calculated from the active power assuming a fixed power factor according to the nominal active / reactive power in electric_grid_ders.

der_timeseries

DER timeseries definition.

Column	Unit	Description
der_model_name		DER model identifier.
time		Timestep in format yyyy-mm-ddTHH:MM:SS (according to ISO 8601).
value	-	Power value (absolute or per unit according to der_models).

der_schedules

DER schedules definition. The timeseries is constructed by obtaining the appropriate values based on the time_period in ddTHH:MM format. Each value is kept constant at the given value for any daytime greater than or equal to HH:MM and any weekday greater than or equal to dd until the next defined ddTHH:MM. Note that the daily schedule is repeated for any weekday greater than or equal to dd until the next defined dd. The initial value for each schedule must start at time_period = 01T00:00.

Column	Unit	Description
der_model_name		DER model identifier.
time_period		Time period in ddTHH:MM format. dd is the weekday (01 - Monday … 07 - Sunday). T is the divider for date and time information according to ISO 8601. HH:MM is the daytime.
value	-	Power value (absolute or per unit according to der_models).

der_cooling_plants

Supplementary cooling plant model parameter definition. The cooling plant model can represent district cooling plants as well as distributed cooling plants. Cooling plants must be connected to both electric and thermal grid, therefore must be defined both in electric_grid_ders and thermal_grid_ders.

Column	Unit	Description
der_model_name		DER model identifier (corresponding to electric_grid_ders / thermal_grid_ders).
cooling_efficiency		Coefficient of performance (COP).
plant_pump_efficiency	-	Pump efficiency (pump power / electric power) of the primary side pumps, i.e. the pumps within the district cooling plant.
condenser_pump_head	m	Pump pressure head across the condenser.
evaporator_pump_head	m	Pump pressure head across the evaporator.
chiller_set_beta	-	Chiller set model beta factor, used to model the chiller efficiency.
chiller_set_condenser_minimum_temperature_difference	K	Chiller set minimum temperature difference at the condenser, i.e. between the condenser water cycle and chiller refrigerant cycle.
chiller_set_evaporation_temperature	K	Chiller set evaporation temperature.
chiller_set_cooling_capacity	W	Chiller nominal maximum cooling capacity.
condenser_water_temperature_difference	K	Condenser water temperature difference.
condenser_water_enthalpy_difference	J/kg	Condenser water enthalpy difference.
cooling_tower_set_reference_temperature_condenser_water	°C	Cooling tower set reference temperature for the condenser water, i.e. the temperature at which condenser water leaves the cooling tower.
cooling_tower_set_reference_temperature_wet_bulb	°C	Cooling tower set reference temperature for the wet bulb ambient air temperature.
cooling_tower_set_reference_temperature_slope	°C	Cooling tower reference temperature slope, used to model the cooling tower efficiency.
cooling_tower_set_ventilation_factor	-	Cooling tower set ventilation factor, used to model the ventilation requirements depending on the condenser water flow.