As its name suggests, the DEC is the link between the buildings and the energy part. The tag DistrictEnergyCenter must have as attributes its unique “id” number, and parameters of its heat transfer fluid : the heat capacity “Cp” in $\mathrm{J/(kg \cdot K)}$, its mass density “rho” in $\mathrm{kg/m^3}$ and its dynamic viscosity “mu”. For now, one can choose the dynamic viscosity among either “0.0004” or “Vogel-Fulcher-Tammann” options, which correspond to a constant value of 0.0004 $\mathrm{Pa \cdot s}$ and the Vogel-Fulcher-Tammann empirical formula for water which depends on temperature.

<DistrictEnergyCenter id="8" Cp="4180" rho="990" mu="Vogel-Fulcher-Tammann">
</DistrictEnergyCenter>

It defines a district energy center with an id of 8 and a heat-transfer fluid of 4180 $\mathrm{J/(kg \cdot K)}$, 990 $\mathrm{kg/m^3}$ and a dynamic viscosity following the Vogel-Fulcher-Tammann empirical formula for water.

It is very easy to get confused about which nodes to assign to which pipes. Here is an explanation so that you understand how to connect the PipePair together.

There are three kinds of nodes :

• NodePair

• SubstationNodePair

• ThermalStationNodePair

When to use wich nodes ? If in the Tag Building there is a tag HeatSource that contains a Subtation or SubstationHP, the Substation must be link to a node. In the District Energy Center a SubstationNodePair is created. It represents the node of the Substation in the Building tag. Then this node can be connected to a pipe. In the District Energy Center when a ThermalStation is created, it must be connected to a ThermalStationNodePair which links to a PipePair. Be careful because each node have to have a different id.

<ThermalStationNodePair id="5" z="1510"/>
<NodePair id="5" z="500.0"/>

It doesn't work because ThermalStationNodePair and NodePair have te same id.

The PipePair tag represents a pipe that is connected to two nodes. Some connections are impossible. PipePair can be connected to :

• two different NodePair

• A NodePair and a SubstationNodePair

• A NodePair and a ThermalStationNodePair

Each DistrictEnergyCenter must have one or more thermal stations. They are defined with the tag ThermalStation which are child elements of the DistrictEnergyCenter. The first two attributes of a ThermalStation are “beginDay” and “endDay” which define when the energy conversion unit is turned on. For example beginDay=”2” and endDay=”364” means the energy conversion unit is turned on from Jan 2^nd to Dec 30^th. Then attribute “linkedNodeId” contains the id of the ThermalStationNodePair that it is connected to. Finally attribute “type” has possibilities “simple” and “seasonalStorageHeating”. The “simple” type can only produce heat or cold.

<ThermalStation beginDay="2" endDay="364" linkedNodeId="4" type="simple"> 
</ThermalStation>

The “seasonalStorageHeating” type can be used with prosumer substations and can store solar thermal heat in its seasonal storage. The “seasonalStorageHeating” type requires another attribute “kvMax” in $\mathrm{m^3/h}$ which describes the valve’s maximal flow coefficient when in storage mode. This type also requires a child element “Storage” to describe the storage tank.

In each Tag ThermalStation there is a Tag Storage has attribute “type”, with only one possibility implemented so far called “simple”. The “simple” type needs attributes “initialTemperature” which describes the storages’s temperature at the start of the simulation in degrees Celsius and “heatCapacity” in $\mathrm{J/kg}$.

<Storage type="simple" initialTemperature="30" heatCapacity="10000000000"/>

All thermal stations need child elements “Pump”, “TemperatureSetpoint”, “PressureSetpoint” and an energy conversion unit.

<ThermalStation type="simple" beginDay="1" endDay="365" linkedNodeId="0"> 
<Pump ... />
<TemperatureSetpoint ... /> 
<PressureSetpoint ... />
<Boiler Pmax="200000" eta_th="0.95"/>
</ThermalStation>

The Pump has attribute “efficiencyPump”, a number between 0 and 1 describing the ratio of hydraulic power given to the fluid over the electrical power consumption. Then attributes “n0” in rotations per min, “a0” in $\mathrm{Pa}$, “a1” in $\mathrm{Pa \cdot s/kg}$ and “a2” in $\mathrm{Pa \cdot s^2/kg^2}$ describe the performance of the pump to increase pressure (see Pierre Cognet’s Master Thesis for further explanations).

<Pump efficiencyPump="0.6" n0="1000" a0="1247180" a1="-1640.236" a2="-0.00016031"/>

The TemperatureSetpoint has a “type” attribute which is among the possibilities “constant”, “affine” and “affineWinterConstantSummer”. The “constant” type needs a “targetSupplyTemp” attribute in degrees Celsuis.

<TemperatureSetpoint type="constant" targetSupplyTemp="80"/>

The “affine” type needs attributes “lowExtTemp”, “highExtTemp”, “lowExtTempSupplyTemp”, “highExtTempSupplyTemp” all in degrees Celsius.

<TemperatureSetpoint type="affine" lowExtTemp="-10" highExtTemp="15" lowExtTempSupplyTemp="90" highExtTempSupplyTemp="75" />

Outputs 90°C when the exterior temperature averaged over the last 24h is below -10°C, outputs 75°C when the exterior temperature averaged over the last 24h is above 15°C, and between these two exterior temperatures it is affine. The “affineWinterConstantSummer” type is similar to affine but needs two more attributes “startSummerTempThreshold” and “endSummerTempThreshold” in degrees Celsius. In summer mode, the temperature setpoint is at a constant value of highExtTempSupplyTemp. To go from winter to summer mode the average exterior temperature must go over the startSummerTempThreshold, and to exit summer mode, it must go below endSummerTempThreshold.

The PressureSetpoint has a “type” attribute which is among the possibilities “constant” and “affine”. The “constant” type needs a “targetPressureDiff” attribute in Pascal.

<PressureSetpoint type="constant" targetPressureDiff="200000"/>

The “affine” needs at least two of attributes “massFlow1”, “massFlow2”, “massFlow3”, etc, in kg/s and at least two of attributes “pressureDiff1”, “pressureDiff2”, “pressureDiff3”, etc, in Pa. One must have massFlowi<massFlowj if i<j. These points define a function affine by parts. For a mass flow through the thermal station below massFlow1, the pressure setpoint is pressureDiff1. For mass flows above massFlowsN (where N is the max value inputed), the pressure setpoint pressureDiffN. Between these values, the function is affine by parts connecting these points.

<PressureSetpoint type="affine" massFlow1="1.375" massFlow2="2.75" massFlow3="17.6"
 massFlow4="32.45" pressureDiff1="180000" pressureDiff2="250000"
 pressureDiff3="390000" pressureDiff4="480000"/>

We speak about Boiler in the Tag Building and more precisely in the Tag HeatSoure. Boiler

The DistrictEnergyCenter tag contains a child element Network. It needs the attribute “soilkValue” in $\mathrm{W/(m \cdot K)}$ describing the thermal conductivity of the soil around the pipes. The Network contains many child elements to describe the pipeline graph structure called the “NodePair”s, “ThermalStationNodePair”s, “SubstationNodePair”s and “Pipepair”s.

<Network soilkValue=”0.5”>
 <ThermalStationNodePair id="0" z="503"/>
 <SubstationNodePair id="1" z="509"/> 
<NodePair id="3" z="504"/>
<SubstationNodePair id="2" z="498"/>
<PipePair id="0" innerRadius="0.06" interPipeDistance="0.5" length="109" node1="0" node2="3"> 
<SupplyPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/> 
<ReturnPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/>
</PipePair>
<PipePair id="1" innerRadius="0.06" interPipeDistance="0.5" length="48" node1="3" node2="1">
<SupplyPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/>
<ReturnPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/> 
</PipePair>
<PipePair id="2" innerRadius="0.05" interPipeDistance="0.5" length="63" node1="3" node2="2"> 
<SupplyPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/>
 <ReturnPipe buriedDepth="1" insulationThick="0.1" insulationkValue="0.04"/>
</PipePair> 
</Network>

The NodePair, ThermalStationNodePair and SubstationNodePair all have the same format. They need an attribute “id”, which is an integer unique to the whole District, not just the current DistrictEnergyCenter. This means that, for example, any NodePair in DistrictEnergyCenter of id=1 has a different id than any SubstationNodePair in DistrictEnergyCenter of id=2. They also have attribute “z” which is the altitude in meters. The node pairs represent two corresponding (or “parallel”) nodes of the network, one is in the supply network, the other in the return network. A node can be a junction between multiple pipes (eg a tee fitting such as in NodePair) or the connection between a pipe and a substation (such as in SubstationNodePair), etc.

<NodePair id="13" z="1500"/>
<SubstationNodePair id="14" z="1500"/>
<NodePair id="15" z="1500"/>
<ThermalStationNodePair id="17" z="1510"/>

The PipePair represents the two parallel pipes in the network. They need an attribute “id”, which is an integer unique to the whole District, not just the current DistrictEnergyCenter. A second attribute is “interPipeDistance” in meters, which is the distance between the central axes of the two parallel pipes. Attribute “length” in meters is the length of the pipes. Attribute “innerRadius” in meters is the radius inside which the fluid flows, so it doesn’t take into account the thickness of the metal pipe nor the insulator (note that this is the same radius for both pipes). Then there are attributes “node1” and “node2”, they contain the ids of the two node pairs that this PipePair connects. Note that they can connect two NodePairs or one NodePair to oneThermalStationNodePair, etc.

The PipePair contains two child elements, the SupplyPipe and the ReturnPipe, to offer the possibility to have different parameters. Each Pipe requires attribute “insulationThick” which is the insulation thickness in meters, the attribute “insulationkValue” which is the insulation thermal conductivity in $\mathrm{W/(m \cdot K)}$ and the attribute “buriedDepth” which the depth below the surface of the pipe in meters.

<PipePair id="0" node1="0" node2="2" length="26.02797805189775" innerRadius="0.04445" interPipeDistance="0.5">
<SupplyPipe insulationThick="0.055549999999999995" insulationkValue="0.023" buriedDepth="1"/>
<ReturnPipe insulationThick="0.055549999999999995" insulationkValue="0.023" buriedDepth="1"/>
</PipePair>