The building - kaemco/CitySim-Solver GitHub Wiki
The Tag Building starts with an identification number (id), an identification string (key), an infiltration rate for the whole building (Ninf), blinds behaviour parameters (BlindsLambda and BlindsIrradianceCutOff) and if the building should be thermally simulated or not (Simulate).
<Building id="1" key="buil34" Ninf="0.4" BlindsLambda=”0.2” BlindsIrradianceCutOff=”100” Simulate="true">It defines a building identified with the identification number "1" (unique per building), a key "buil34" that can be alphanumeric, an infiltration rate of 0.4 volume per hour (ACH), an irradiance cut-off for the automatic blinds of 100 W/m2 with a smooth transition (λ=0.2) and a thermal simulation tag set to “true”.
The blinds behaviour is simulated by a Sigmoid transition between fully open and fully closed https://www.wolframalpha.com/input/?i2d=true&i=plot+Divide%5B1%2C%5C%2840%291%2Bexp%5C%2840%290.2*%5C%2840%29x-100%5C%2841%29%5C%2841%29%5D+from+0+to+500 in which you can change the default values of 0.2 and 100 W/m2.
The tag building contains also information about the heat, cool and domestic hot water (DHW) tanks that are in between the energy conversion systems and the space heating, cooling and domestic hot water demands.
<HeatTank V="0.01" phi="20.0" rho="1000.0" Cp="4180.0" Tmin="30.0" Tmax="35.0" Tcritical="90.0"/>
<DHWTank V="0.2" phi="20.0" rho="1000.0" Cp="4180.0" Tmin="50.0" Tmax="70.0" Tcritical="90.0" Tinlet="5.0"/>
<CoolTank V="0.01" phi="20.0" rho="1000.0" Cp="4180.0" Tmin="5.0" Tmax="20.0"/>They represent three tanks of 0.01 m3 of a liquid of density 1000 kg/m3, specific heat of 4180 J/(kg K), the thermal losses of the tank are of 20 W/K, the requested temperature range is between 20°C and 35°C and then 90°C as the critical temperature for the heat tank, 5°C and 20°C for the cool tank and the range is between 50°C and 70°C with a critical temperature of 90°C for the DHW tank and its inlet water temperature is given as 5°C.
There is also a Tag HeatSource in the Tag Building. The tag HeatSource can contain the Tag Substation, Boiler, HeatPump but also the Tag CHP and CHP-HP which represents respectively Combined Heat and Power and Combined Heat and Power with a HeatPump. The HeatSource tag can only contain one source. For example :
<HeatSource beginDay="288" endDay="135">
<Boiler Pmax="500000" eta_th="0.96" name="boiler1"/>
</HeatSource>A special feature of the HeatSource is the prosumer. The “prosumer” type represents the possibility to inject solar thermal heat into the network. To inject the heat, it pumps the fluid from return to supply at a desired mass flow rate to the setpoint temperature, with the setpoint differential pressure. Therefore it needs a pump and a flow control valve. To define these, the substation must have attribute “kvMaxFlowControlValve” which is the maximal flow coefficient of the flow control valve in m^3/h. The Substation must have child elements that define a Pump, a TemperatureSetpoint and a PressureSetpoint.
<HeatSource beginDay="258" endDay="135">
<Substation type="prosumer" kvMaxFlowControlValve="1000" designEpsilon="0.6"
designTempDifference="40"
designThermalPower="15000" linkedNodeId="2">
<TemperatureSetpoint type="constant" targetSupplyTemp="70"/>
<PressureSetpoint type="constant" targetPressureDiff="200000"/>
<Pump efficiencyPump="0.6" n0="1000" a0="1247180" a1="-1640.236" a2="-0.00016031"/>
</Substation>
</HeatSource>HeatSource Tag can also take a simple Boiler like this example:
<HeatSource beginDay="288" endDay="135">
<Boiler Pmax="500000" eta_th="0.96"/>
</HeatSource>Boiler has a maximum power (Pmax) of 500000 W, a thermal efficiency (eta_th) of 0.96. The results will show a Fuel Consumption.
An air heat pump is given by the following parameters:
<HeatSource>
<HeatPump Pmax="1000" eta_tech="0.3" Ttarget="55" Tsource="air"/>
</HeatSource>where Pmax is the maximum electrical power, eta_tech is the technical efficiency, Ttarget is the target temperature and Tsource is defined as the outdoor air temperature.
A ground heat pump is given by the following parameters:
<HeatSource>
<HeatPump Pmax="1000" eta_tech="0.3" Ttarget="55" Tsource="ground" depth="5.0" z1="10.0" alpha="0.07"/>
</HeatSource>with maximum electrical power of 1000 W, a target temperature of 55°C, a technical efficiency of 0.3, a ground source temperature with vertical pipes from 5 m to 10 m deep in a soil thermal diffusivity of 0.07
The HeatSource tag can also take a cogeneration heat and power (CHP) as in the following example:
<HeatSource beginDay="288" endDay="135">
<CHP Pmax="5000" eta_th="0.35" eta_el="0.60" minPartLoadCoeff="0.2"/>
</HeatSource>with a maximum thermal power of 5000 W, a thermal efficiency of 0.35 and an electrical efficiency of 0.6, a minimum part load coefficient of 0.2 (under which the cogeneration device does not start).
The cogeneration can be combined with a heat pump, in which configuration the electricity produced is used to run the heat pump.
<HeatSource>
<CHP-HP Pmax="1000" eta_th="0.6" eta_el="0.4" minPartLoadCoeff="0.2">
<HeatPump Pmax="1000" eta_tech="0.3" Ttarget="55" Tsource="ground" position="vertical" depth="5.0" z1="10.0" alpha="0.07"/>
</CHP-HP>
</HeatSource>in which we have the same parameters as for the CHP but in addition we have to add the parameters of a HeatPump.
To add a Substation to a building, one must in the scope of tag Building, to either the HeatSource or CoolSource child element add the Substation tag. Substations must have attribute “linkedNodeId” which is the id of the SubstationNodePair to which it is linked. It also has attribute “designThermalPower” describing the nominal thermal power that can be exchanged at the substation, in Watts and always positive even if it is a CoolSource. It also has attribute “designTempDifference” which is the temperature difference the substation aims to have (especially at nominal power), in degrees Celsius and always positive. It also has attribute “designEpsilon”, a number between zero and one, describing the performance to exchange heat (linked to the effectiveness method, see documentation for further detail). Substations also have the attribute “type” which can be “simple” or “prosumer”. For the “simple” type, nothing more is needed.
<CoolSource beginDay="136" endDay="257">
<Substation type="simple" designEpsilon="0.8" designTempDifference="10" designThermalPower="8000" linkedNodeId="39"/>
</CoolSource>In Tag HeatSource there may be a SubstationHP which means that the substation behaves like a HeatPump.
<HeatSource beginDay="258" endDay="135">
<SubstationHP linkedNodeId="7" designThermalPower="360000" designTempDifference="5" designEpsilon="0.6" type="simple" Pmax="360000" eta_tech="0.3" Ttarget="70" Tsource="ground" position="vertical" depth="5" z1="10" alpha="0.07"/>
</HeatSource>The input parameters for the SubstationHP are the same as for the Substation. The additional parameters are those that characterise the HeatPump. Pmax represents the electrical capacity of the HeatPump.
In each Tag Building there is also a Tag CoolSource. And in each CoolSource there is a Tag Substation or a HeatPump.
<CoolSource>
<HeatPump Pmax="1.0E7" eta_tech="0.3" Ttarget="5.0" Tsource="air"/>
</CoolSource>In the above example, the heat pump bringing refrigeration has a Ttarget of 5°C.
In each Tag Building there are as many Tags Zones as necessary to describe the building. Each Zone corresponds to a thermal zone and contains Walls, Roofs, Floors, Surfaces and ZoneSurfaces. Moreover, it contains the zone id, volume, the total losses due to linear and punctual thermal bridges and if the zone is situated on the ground floor.
<Zone id="1" volume="1179.0686399999995" Psi="0.3" groundFloor="false">
<Occupants ...>
<Walls ... >
...
< /Walls>
<Roofs ... >
...
</Roofs>
<Floors ... >
...
</Floors>
<ZoneSurface ... >
... </ZoneSurface>
</Zone>It defines a zone with an id of 1, a volume of about 1179 m3, total losses due to thermal bridges of 0.3 W/K and not at the ground level. Moreover, the Zone may contain Occupants, Walls, Roofs, Floors and ZoneSurfaces that are defined in what follows.
In each Tag Zone there is Tag Occupants, which is necessary to describe occupant profile. Each occupant contains number of occupants, reference to the type of yearly occupant profile, simulation type (deterministic or stochastic) and activity type. Moreover, number of occupants can also be defined as occupants per unit area depending on the type of building (hotel, residential, mall etc).
<Occupants n="10.0" sensibleHeat="90" sensibleHeatRadiantFraction="0.6" type="1" stochastic="true" activityType="1" DHWType="1"/>It defines number of occupants as 10, yearly occupant profile type is 1 and stochastic is true which corresponds to stochastic simulation, activity type is 1 and finally DHWType is 1. Each occupant has a sensible heat release of 90 W, a sensible heat radiant fraction of 0.6. Note: by default when stochastic is not given for the simulation, it will be assumed as false. Hence, a deterministic simulation will be performed.
In each Tag Zone there are as many Tags Walls as necessary to describe the building. Each wall contains a reference to the wall type that contains its physical information for a simulation with thermal inertia, or just a U-value for a simplier approximation. The information is completed by the short wave reflectance of the wall, its glazing ratio, the glazing's g-value, U-value and openable ratio. Moreover, it contains the vertices of the wall.
<Wall id="57" type="7" ShortWaveReflectance="0.2" GlazingRatio="0.3" GlazingGValue="0.7" GlazingUValue="1.4" OpenableRatio="0.5" LongWaveEmissivity="0.5" >
<V0 x="156.28604298012556" y="2.6159466366386184" z="0.0"/>
<V1 x="56.33630857784846" y="2.6159466366386184" z="0.0"/>
<V2 x="56.33630857784846" y="2.6159466366386184" z="20.0"/>
<V3 x="156.28604298012556" y="2.6159466366386184" z="20.0"/>
</Wall>It defines a wall with 4 vertices, of Composite type 7, with all other parameters easily readable in the XML format. if you do not set LongWaveEmissivity its default value is 0.9. The walls can be fitted with photovoltaic panels and/or solar heaters, and for that the Wall tag can be completed with details about the panel(s).
<Wall id="57" type="7" ShortWaveReflectance="0.2" GlazingRatio="0.3"
GlazingGValue="0.7" GlazingUValue="1.4" OpenableRatio="0.5">
<PV pvRatio="0.5" Pmp="120" Ac="1.07" Tref="25" Tcnoct="47"
muVoc="-0.08" Vmp="16.8"/>
<ST stRatio="0.1" eta0="0.778" a1="3.59" a2="0.0096"/>
<V0 x="156.28604298012556" y="2.6159466366386184" z="0.0"/>
<V1 x="56.33630857784846" y="2.6159466366386184" z="0.0"/>
<V2 x="56.33630857784846" y="2.6159466366386184" z="20.0"/>
<V3 x="156.28604298012556" y="2.6159466366386184" z="20.0"/>
</Wall>It defines that PV panels from BP Solar identified by SX-120S cover 50% of the wall (pvRatio) are installed together with a solar heater Conergy Aldo 240 that covers 10% of the wall. Moreover the wall is not referring to a wall type, but rather giving a U-value. This also defines solar thermal panel with 10% of wall cover, efficiency as 77.8% (eta0) and a1 (3.59) and a2 (0.0096) are the heat loss coefficients that can be obtained from the specification sheet from the manufacturer. Note: by default when no openableRatio is given for the glazings, its value is assumed to be 25%. In a thermal zone, all the walls must have the same type, but not necessary the same U-values.
In each Tag Zone there are as many Tags Roofs as necessary to describe the building's roof. The roofs are a simplified version of the walls, they can be defined by roof type (for which the U-value will be calculated by the solver) or attributed directly with a roof U-value within a Composite.
<Roof id="55" type="9" ShortWaveReflectance="0.2" GlazingRatio="0.0"
GlazingGValue="0.7" GlazingUValue="1.382436" OpenableRatio="0.5">
<V0 x="156.28604298012556" y="-87.43429282902677" z="20.0"/>
<V1 x="156.28604298012556" y="2.6159466366386184" z="20.0"/>
<V2 x="56.33630857784846" y="2.6159466366386184" z="20.0"/>
<V3 x="56.33630857784846" y="-87.43429282902677" z="20.0"/>
</Roof>It defines a roof with 4 vertices and a composite of type 9, with all other parameters easily readable in the XML format. The roofs can be fitted with PV panels just like the walls. Also, roofs can be fitted with micro wind turbine and the Roof tag can be completed with details about the wind turbine and its location characteristics.
<Roof id="55" type="9" ShortWaveReflectance="0.2" GlazingRatio="0.0"
GlazingGValue="0.7" GlazingUValue="1.382436" OpenableRatio="0.5">
<MicroWindTurbine cutInSpeed="3" ratedSpeed="14" cutOutSpeed="16"
c1="28.98" c2="-66.63" c3="180.8" airDensity="1.2" Height="2" Gamma="0.25"
Alpha="0.67"/>
<V0 x="156.28604298012556" y="-87.43429282902677" z="20.0"/>
<V1 x="156.28604298012556" y="2.6159466366386184" z="20.0"/>
<V2 x="56.33630857784846" y="2.6159466366386184" z="20.0"/>
<V3 x="56.33630857784846" y="-87.43429282902677" z="20.0"/>
</Roof>It defines a MicroWindTurbine with cut-in speed of 3 m/s, rated speed of 12 m/s, cut-out speed of 16 m/s and curve fitting coefficients c1, c2 and c3. These coefficients can be obtained by fitting the power curve obtained from the manufactures with a polynomial function between the cut-in speed and the rated speed. For example, in the Figure below, the power curve is fitted from 3 m/s to 14 m/s and c1 is 28.96, c2 is -66.63 and c3 is 180.8. The airDensity parameter of 1.2 kg/m3 is the atmospheric air density in which the micro wind turbine was tested and provided in the specification sheet from the manufacturer. The turbine hub height is 2 m, and Alpha of 0.25 and Gamma of 0.67 are parameters from the terrain description around the turbine (see the Table below). Note: the micro wind turbine uses the building height (z coordinate of the centroid of the roof) in the model where the z-axis origin is taken at the meteorological station altitude.
In Walls, Roofs, and Surfaces a PV Tag can be added to simulate the presence of PV panels on each specific element. Each PV Tag is attached to the surface element to cover with panels and includes the technical properties of the panels.
<Wall GlazingGValue="0.47" GlazingRatio="0.1" GlazingUValue="2.3" OpenableRatio="0.5" ShortWaveReflectance="0.2" id="233702" type="107">
<PV Etampref="0.21" Tcnoct="45" Tref="25" Vmp="57.3" muVoc="-0.1674" name="SunPower X21-335-BLK" pvRatio="1.0" />
<V0 x="-497.84899999946356" y="-1047.109700000845" z="649.1275273789063" />
<V1 x="-499.1655000001192" y="-1047.2646999983117" z="649.7595273789063" /><Roof GlazingGValue="0.7" GlazingRatio="0.3" GlazingUValue="1.4" OpenableRatio="0.0" ShortWaveReflectance="0.2" id="233686" type="119">
<PV Etampref="0.21" Tcnoct="45" Tref="25" Vmp="57.3" muVoc="-0.1674" name="SunPower X21-335-BLK" pvRatio="1.0" />
<V0 x="-481.8339999988675" y="-1042.0069999983534" z="652.9735273789063" />
<V1 x="-491.53310000151396" y="-1043.1454000016674" z="653.2828273789062" />The examples define a PV panel with a reference efficiency of 21%, a nominal operating cell temperature of 45°C, a reference temperature (module temperature conditions during reference measurements) of 25°C, a voltage at a maximum power of 57.3 V, a voltage temperature coefficient of V/°C, the reference name of the product and a pvRatio of 1.0. Please note that pvRatio does not take into account GlazingRatio and it eventually overwrites the glazing surface of the element: e.g. if the GlazingRatio is set to 0.8 and pvRatio is set to 0.5, only 0.5 of glazing area is actually simulated on the element.
The software already takes into account the effect of view factors according to the panel tilt angle. Within the PV model, however, the user can specify the Incident Angle Modifier coefficients to take into account the Fresnel Effect for the glass surfaces of the PV panels (https://en.wikipedia.org/wiki/Fresnel_equations). The IAM function represents the relation between the angle of incidence, in radians, and the light transmission coefficient. The software computes a polynomial function: the user's defined parameters represent the coefficients of the trendline of the aforementioned correlation. The number of the final coefficient indicates the degree of the polynomial function desired.
<Wall GlazingGValue="0.47" GlazingRatio="0.5" GlazingUValue="2.3" OpenableRatio="0.5" ShortWaveReflectance="0.2" id="233742" type="107">
<PV Etampref="0.226" Tcnoct="41.5" Tref="25" Vmp="64.8" muVoc="-0.1768" name="Sunpower_SPR_MAX3_400" pvRatio="1.0">
<IAM c0="0.96" c1="0.6246" c2="-3.9912" c3="10.42" c4="-13.472" c5="8.542" c6="-2.14" />
</PV>In the example, the trendline for the specified kind of PV panel has the following sixth-degree polynomial equation:
y = -2.14x^6 + 8.542x^5 - 13.472x^4 + 10.42x^3 - 3.9912x^2 + 0.6246^x + 0.96.
The coefficient c0 is the constant term of the equation, while c1 to c6 are the coefficients related to the 'x' variable of according degree.
In each Tag Zone there are as many Tags Floors as necessary to describe the building's ground floor. A floor represents the surface area considered in contact with the soil and its conductance is computed from the Composite given as a reference or attributed directly with the U-value given in the Composite.
<Floor id="54" type="10">
<V0 x="56.33630857784846" y="-87.43429282902677" z="0.0"/>
<V1 x="56.33630857784846" y="2.6159466366386184" z="0.0"/>
<V2 x="156.28604298012556" y="2.6159466366386184" z="0.0"/>
<V3 x="156.28604298012556" y="-87.43429282902677" z="0.0"/>
</Floor>In each Tag Zone there are as many Tags ZoneSurface as necessary to describe the surfaces that interconnect the thermal zones. They need as primary information the Area of the surface, if the surface is vertical or not, the wall type and the id of the zone it is connected to.
<ZoneSurface Area="15" type="9" Vertical="true" LinkZone="2"/>It refers to a vertical wall type number 9 of area 15m2 in contact with zone 2
Some parts of the building may create shade on other parts but does not count towards the calculation of the heated volume, such as the overhanging roofs, for example. To introduce this type of element, they must be added as a follow-up:
<Surface id="54" type="10” ShortWaveReflectance="0.2">
<V0 x="56.33630857784846" y="-87.43429282902677" z="0.0"/>
<V1 x="56.33630857784846" y="2.6159466366386184" z="0.0"/>
<V2 x="156.28604298012556" y="2.6159466366386184" z="0.0"/>
<V3 x="156.28604298012556" y="-87.43429282902677" z="0.0"/>
</Surface>Sometimes, ones has to be careful, if the surface has to generate shadow in two direction, the same element must appear two times. In both, there is the same vertices but in two opposite direction (v0-v1-v2-v3; v3-v2-v1-v0).
It is possible that you will be required to submit an energy demand per building. In this case you will have to provide CitySim with the necessary energy in Watts for each hour.
<ImposedHeatDemand d1h1="25776.66666666666" d1h2="28226.611111111128"
d1h3="55942.33333333336" d1h4="29678.000000000004" d1h5="32000.222222222223"
d1h6="27843.44444444444" d1h7="39268.77777777778" d1h8="36969.77777777777"
d1h9="33440.0" d1h10="31245.499999999996" .... d365h24="35457.562548"Where d represents the day h the hour of each day. The energy demand is given in W.