Guidelines_EnergyADE.md 78.4 KB
Newer Older
1
# Overview of the Energy Application Domain Extension
2

RomainNouvel's avatar
RomainNouvel committed
3
## Motivation and design objectives
4

RomainNouvel's avatar
RomainNouvel committed
5
The CityGML Energy Application Domain Extension (Energy ADE) aims at extending the CityGML 2.0 standard with energy-related entities and attributes necessary to perform energy analyses at urban scale, such as energy demand diagnostics, solar potential study, simulation of low-carbon energy strategies etc...
Esteban Munoz's avatar
Esteban Munoz committed
6

RomainNouvel's avatar
RomainNouvel committed
7
8
9
In accordance with the philosophy of CityGML, the Energy ADE aims to be flexible in terms of compatibility with different data qualities and levels of details. His design is driven by the following objectives : 
- store and manage energy-related data collected at urban scale, based on the standard data specification of INSPIRE Directive of the European Parliament, as well as the recent US Building Energy Data Exchange Specification (BEDES). 
- provide information data required by different urban energy models and simulation (e.g. from standard energy balance methods as of ISO 13790, to sub-hourly dynamic simulations by means of software programs like CitySim or EnergyPlus)
10

RomainNouvel's avatar
RomainNouvel committed
11
12
13
## General structure overview

Its structure is conceived to be modular, so as to be potentially used and extended also for other applications (e.g. module Occupancy for socio-economics, module Construction and Materials for acoustics or statics, etc). It consists of 5 modules:
gioagu's avatar
gioagu committed
14
15
16
- Building Physics module,
- Occupancy module,
- Construction and Material module,
RomainNouvel's avatar
RomainNouvel committed
17
- Energy Use and System module,
gioagu's avatar
gioagu committed
18
19
- Timeseries and Schedules module.

RomainNouvel's avatar
RomainNouvel committed
20
21
22
23
24
25
The Building Physics module is the core of the Energy ADE. It extends the existing CityGML objects (Abstract Building, BoundarySurface and Opening) and relate them to new thermal entities (ThermalZone, ThermalBoundary, resp. ThermalComponent). Its central object is the ThermalZone, which is the volume unit for heat/cool energy demand calculation.

The Occupancy module is related to the CityGML model (AbstractBuilding) and Building Physics Module (ThermalZone) through its central object : UsageZone. The latter is the spatial unit for user-depending energy use study (e.g. domestic hot water, electrical appliances) and can provide usage boundary conditions for the heat/cool energy demand calculations.

The Construction and Material, Energy Use and System, and Timeseries and Schedules modules are independant « floating modules » which may be connected to different CityGML and Energy ADE CityObjects. 

gioagu's avatar
gioagu committed
26

RomainNouvel's avatar
RomainNouvel committed
27
This document is intended to explain the characteristics and purposes of each module, their entities and attributes. It provides also a number of XML examples, illustrating how and where the Energy ADE entities and attributes may be embedded into CityGML.
28

29
# Building Physics Module
30

31
32
## Module overview and main relationships

RomainNouvel's avatar
RomainNouvel committed
33
34
![Class diagram of Building Physics Module](fig/BuildingPhysics_onlyFeature.png)

RomainNouvel's avatar
RomainNouvel committed
35
...and its types and codelists
RomainNouvel's avatar
RomainNouvel committed
36
![Types and Codelists of Building Physics Module](fig/BuildingPhysics_onlyTypesAndCodelists.png)
RomainNouvel's avatar
RomainNouvel committed
37

38
39
40
41
42
Main purpose of this module is building thermal modeling (e.g. calculation of space heating and space cooling demands).

Thus, it extends the existing CityGML objects `_AbstractBuilding`, `_BoundarySurface`and `_Opening` with energy-related attributes, and define new thermal building objects `ThermalZone`, `ThermalBoundary`, respectively `ThermalComponent` related to them.

The `ThermalZone `is the unit volume for heating and cooling demand calculation. A Building may have several `ThermalZone`, for instance in the case of mixed-usage building, or to distinguish rooms or zones with different orientations (i.e. solar gains) and/or thermal behaviour.
Esteban Munoz's avatar
Esteban Munoz committed
43

44
These `ThermalZone` objects are separated from each other and from the outside by `ThermalBoundary` objects. These `ThermalBoundary` objects may or not correspond to the CityGML `_BoundarySurface`.
45

46
If occupied, a `ThermalZone` must be related to at least 1 `UsageZone`, which contains the usage boundary conditions required for the heating and cooling demand calculation (see Occupancy Module). One `ThermalZone` may be related to several `UsageZone` for simplified modelling of mixed-usage space, in which case the usage boundary conditions of the `UsageZone` should be aggregated or weighted according with their floorArea.
47

RomainNouvel's avatar
RomainNouvel committed
48
## Extension of CityGML building objects
49

50
### \_AbstractBuilding
gioagu's avatar
gioagu committed
51

Esteban Munoz's avatar
Esteban Munoz committed
52
The Energy ADE extends the CityGML _AbstractBuilding by a number of
Esteban Munoz's avatar
Esteban Munoz committed
53
energy-related attributes, e.g with regards to the geometrical characteristics
54
(`referencePoint`, `volume`, `floorArea`, `hightAboveGround`), to the
Esteban Munoz's avatar
Esteban Munoz committed
55
56
available energy certificates (`energyPerformanceCertification`) and
refurbishment measures (`RefurbishmentMeasureOnBuilding`), and other building
57
58
information useful for building typology categorisations (`buildingType`,
`constructionWeight`,`isLandmarked`).
59

60
All these attributes are optional. Some of them, like `volume`, `floorArea` and  
Esteban Munoz's avatar
Esteban Munoz committed
61
62
`energyPerformanceCertification`, have a cardinality [0..*] and may
consequently be attributed several times to a building, specifying different
63
values for different kinds of `VolumeType`, `FloorArea` and `ÈnergyPerformanceCertification`respectively.
64

Esteban Munoz's avatar
Esteban Munoz committed
65
Finally, because `_AbstractBuilding` inherits from `_CityObject`, further
66
objects may be assigned to it, like `WeatherData`and `EnergyDemand`(see Module
Esteban Munoz's avatar
Esteban Munoz committed
67
Energy and Systems).
68

Esteban Munoz's avatar
Esteban Munoz committed
69
70
In the following, an extract of CityGML file for a building is given, included
some of its Energy ADE attributes.
gioagu's avatar
gioagu committed
71
72

```xml
gioagu's avatar
gioagu committed
73
74
<!--Examples of Building with Energy ADE attributes-->
<bldg:Building gml:id="id_building_1">
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
  <gml:description>Description of Building 1</gml:description>
  <gml:name>Name of Building 1</gml:name>
  <energy:referencePoint>
   <gml:Point gml:id="id_building_referencepoint_1" srsName="EPSG:31256" srsDimension="3">
    <gml:pos>2525.5 338567.5 162.6</gml:pos>
   </gml:Point>
  </energy:referencePoint>
  
  <energy:energyPerformanceCertification>
   <!--Here come the EnergyPerformanceCertification objects (see later) -->
  </energy:energyPerformanceCertification>
  
  <energy:heightAboveGround>
   <energy:HeightAboveGround>
    <energy:heightReference>highestEave</energy:heightReference>
    <energy:value uom="m">10.0</energy:value>
   </energy:HeightAboveGround>
  </energy:heightAboveGround>
  
  <energy:heightAboveGround>
   <energy:HeightAboveGround>
    <energy:heightReference>topOfConstruction</energy:heightReference>
    <energy:value uom="m">13.0</energy:value>
   </energy:HeightAboveGround>
  </energy:heightAboveGround>
100
 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
<energy:volume>
 <energy:VolumeType>
  <energy:type>GrossVolume</energy:type>
  <energy:value uom="m3">1050</energy:value>
 </energy:VolumeType>
</energy:volume> 
  
  <energy:refurbishmentMeasureOnBuilding>
   <energy:RefurbishmentMeasure>
    <!--Here come all attributes of a RefurbishmentMeasure object (omitted here)-->
   </energy:RefurbishmentMeasure>
  </energy:refurbishmentMeasureOnBuilding>
    
  <!--Here may come a list of UsageZone of the building (see Module Occupancy) -->
  
  <energy:isLandmarked>false</energy:isLandmarked>
  <energy:floorArea>
   <!--Here come the floorArea objects (see later)-->
  </energy:floorArea>
  
  <energy:constructionWeight>Heavy</energy:constructionWeight>
  <energy:buildingType>MultiFamilyHouse</energy:buildingType>
  
  <!--Here follow all ThermalZone objects, each inside a "thermalZones" tag-->
  <energy:thermalZone>
   <energy:ThermalZone gml:id="id_thermalzone_1">
    <!--Here come all attributes of the first ThermalZone (omitted here)-->
   </energy:ThermalZone>
  </energy:thermalZone>
  <energy:thermalZone>
   <energy:ThermalZone gml:id="id_thermalzone_2">
    <!--Here come all attributes of the second ThermalZone (omitted here)-->
   </energy:ThermalZone>
  </energy:thermalZone>
 </bldg:Building>
gioagu's avatar
gioagu committed
136
137
138
139
```

#### FloorArea

Esteban Munoz's avatar
Esteban Munoz committed
140
141
Buildings (`_AbstractBuilding`) and building zones (`ThermalZone` and
`UsageZone`) may have several `floorArea`, related to several `FloorAreaType`
142
(e.g. net floor area, gross floor area, energy reference area).
143

gioagu's avatar
gioagu committed
144
```xml
145
<!--Examples of three floor areas-->
146
<energy:floorArea>
147
148
	<energy:FloorArea>
		<energy:type>GrossFloorArea</energy:type>
149
		<energy:value uom="m2">50.0</energy:value>
150
	</energy:FloorArea>
151
152
153
</energy:floorArea>

<energy:floorArea>
154
155
	<energy:FloorArea>
		<energy:type>NetFloorArea</energy:type>
156
		<energy:value uom="m2">40.0</energy:value>
157
	</energy:FloorArea>
158
159
160
</energy:floorArea>

<energy:floorArea>
161
162
	<energy:FloorArea>
		<energy:type>EnergyReferenceArea</energy:type>
163
		<energy:value uom="m2">43.0</energy:value>
164
	</energy:FloorArea>
gioagu's avatar
gioagu committed
165
</energy:FloorArea>
gioagu's avatar
gioagu committed
166
167
```

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
#### VolumeType

Buildings (`_AbstractBuilding`) and thermal zones (`ThermalZone`) may have several `volume`, related to several `VolumeType`
(e.g. net volume, gross volume, energy reference volume).

```
xml

<energy:volume>
 <energy:VolumeType>
  <energy:type>NetVolume</energy:type>
  <energy:value uom="m3">900</energy:value>
 </energy:VolumeType>
</energy:volume> 
 
<energy:volume>
 <energy:VolumeType>
  <energy:type>GrossVolume</energy:type>
  <energy:value uom="m3">1050</energy:value>
 </energy:VolumeType>
</energy:volume> 
  
<energy:volume>
 <energy:VolumeType>
  <energy:type>EnergyReferenceVolume</energy:type>
  <energy:value uom="m3">975</energy:value>
 </energy:VolumeType>
</energy:volume>   
```

gioagu's avatar
gioagu committed
198
199
#### EnergyPerformanceCertification

200
201
A building may present several  
`energyPerformanceCertification` related to
Esteban Munoz's avatar
Esteban Munoz committed
202
203
different `certificationName` (e.g. PassivHaus, LEED) and/or different
certification dates (specificied by `certificationId`).
204

gioagu's avatar
gioagu committed
205
```xml
206
<!--Example of two energy performance certifications-->
Joachim Benner's avatar
Joachim Benner committed
207
208
<energy:energyPerformanceCertification>
    <energy:EnergyPerformanceCertification>
209
210
        <energy:certificationRating>Platinum</energy:certificationRating>
        <energy:certificationName>LEED</energy:certificationName>
Joachim Benner's avatar
Joachim Benner committed
211
        <energy:certificationId>0815</energy:certificationId>
212
213
214
215
216
    </energy:EnergyPerformanceCertification>
    <energy:EnergyPerformanceCertification>
        <energy:certificationRating>Passive house</energy:certificationRating>
        <energy:certificationName>EnerPHit</energy:certificationName>
        <energy:certificationId>4756</energy:certificationId>
217
    </energy:EnergyPerformanceCertification>
Joachim Benner's avatar
Joachim Benner committed
218
</energy:energyPerformanceCertification>
219

gioagu's avatar
gioagu committed
220
221
222
223
```

#### RefurbishmentMeasure

Esteban Munoz's avatar
Esteban Munoz committed
224
225
226
227
Energy-efficient refurbishment operations and measures may be indicated as
attribute of `_AbstractBuilding`, `_BoundarySurface` and `_Opening`. The
`RefurbishmentMeasure` object contains two information: the date and level of
refurbishment.
228

Esteban Munoz's avatar
Esteban Munoz committed
229
230
231
232
233
234
235
The attribute `levelOfRefurbishment` is a codeList whose elements generally
relates to refurbishment measure libraries or to a building typology
categorisation.

The attribute `dateOfRefurbishment` is defined by the GML type `DateOfEvent`,
and may consequently be specified in different manners (see the 3 examples
below).
236

gioagu's avatar
gioagu committed
237
```xml
238
<!--Example of a Refurbishment Measure on a building with a very vague date ("before June 2010") -->
239
240
241
242
243
244
245
246
247
 <bldg:Building>
  <energy:refurbishmentMeasureOnBuilding>
   <energy:RefurbishmentMeasure>
    <energy:dateOfRefurbishment>
     <energy:DateOfEvent>
      <energy:instant indeterminatePosition="before">2010-06</energy:instant>
     </energy:DateOfEvent>
    </energy:dateOfRefurbishment>
    <energy:levelOfRefurbishment>UsualRefurbishment</energy:levelOfRefurbishment>
248
    <energy:descriptionOfRefurbishment>...</energy:descriptionOfRefurbishment>
249
250
251
   </energy:RefurbishmentMeasure>
  </energy:refurbishmentMeasureOnBuilding>
  </bldg:Building>
gioagu's avatar
gioagu committed
252
253
```

254
255
256
257
```xml
<!--Example of an advanced Refurbishment Measure in the years 1998 and 1999 -->
<energy:refurbishmentMeasureOnBuilding>
    <energy:RefurbishmentMeasure>
258
259
260
261
262
263
264
265
266
267
268
     <energy:dateOfRefurbishment>
      <energy:DateOfEvent>
       <energy:period>
        <gml:TimePeriod>
         <gml:beginPosition>1998</gml:beginPosition>
         <gml:endPosition>2000</gml:endPosition>
        </gml:TimePeriod>
       </energy:period>
      </energy:DateOfEvent>
     </energy:dateOfRefurbishment>
     <energy:levelOfRefurbishment>AdvancedRefurbishment</energy:levelOfRefurbishment>
269
    </energy:RefurbishmentMeasure>
270
   </energy:refurbishmentMeasureOnBuilding>
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
```

```xml
<!--Example of an usual Refurbishment Measure in June 2012 -->
<energy:refurbishmentMeasureOnBuilding>
    <energy:RefurbishmentMeasure>
        <energy:dateOfRefurbishment>
            <energy:DateOfEvent>
                <energy:instant>2012-06</energy:instant>
            </energy:DateOfEvent>
        </energy:dateOfRefurbishment>
        <energy:levelOfRefurbishment>UsualRefurbishment</energy:levelOfRefurbishment>
    </energy:RefurbishmentMeasure>
</energy:refurbishmentMeasureOnBuilding>
```

287
288
### WeatherData

289
290
291
292
293
294
295
Time series of measured or processed meteorological or radiation parameters may 
be related with any feature class of the base standard (e.g. `_AbstractBuilding`,
`_BoundarySurface`) or the extension (e.g. `ThermalBoundary`) via the property
`weatherData`. The corresponding type `WeatherData` has three properties: The 
type of the weather data (`weatherDataType`), the time seris of values (`values`),
and optionally the position of the sensor (`position`). The following types of 
meteorological and radiation data can be specified:
296

297
298
299
300
301
302
303
304
305
306
- `AirTemperature`
- `Humidity`
- `WindSpeed`
- `Cloudiness`
- `GlobalSolarIrradiance` (see \_BoundarySurface)
- `DirectSolarIrradiance`
- `DiffuseSolarIrradiance`
- `TerestrialEmission`
- `DownwardTerrestrialRadiation`
- `DaylightIlluminance` (see \_BoundarySurface)
307

308
309
### \_Opening

Esteban Munoz's avatar
Esteban Munoz committed
310
311
The CityGML abstract class `_Opening` (inherited by the objects `Window` and
`Door`) is extended in this Energy ADE by a number of energy-related
312
attributes.
313

Esteban Munoz's avatar
Esteban Munoz committed
314
315
316
317
First of all, an optional attribute `openableRatio` details the proportion of
the opening area which may be opened. An indoor and an outdoor shading system
may complement the opening, with a `ShadingType` characterized by a
`transmittance` (see details in Module Materials and Constructions) and a
318
319
320
`maximumCoverRatio`. Finally, material information (`AbstractConstruction`, 
see Module Materials and Constructions) may be specified for the opening via 
the `openingConstruction` attribute.
321

Esteban Munoz's avatar
Esteban Munoz committed
322
323
324
As in the Building example shown before, the standard CityGML attributes have
been omitted for better readability. The door example is simpler and contains
also information about construction and construction orientation (by means of
Esteban Munoz's avatar
Esteban Munoz committed
325
Xlinks).
326
327
328
329

```xml
<!--Example of a Window object -->
<bldg:Window gml:id="id_window_1">
330
	<gml:description>This is window with an outside rolling shutter and curtains inside</gml:description>
331
	<gml:name>Window with rolling shutter and curtains</gml:name>
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363

	<energy:outdoorShading>
		<energy:ShadingType>
			<energy:maximumCoverRatio uom="ratio">1</energy:maximumCoverRatio>
			<energy:name>Rolling shutter</energy:name>
			<energy:transmittance>
				<energy:Transmittance>
					<energy:fraction uom="ratio">0</energy:fraction>
					<energy:wavelengthRange>Total</energy:wavelengthRange>
				</energy:Transmittance>
			</energy:transmittance>
		</energy:ShadingType>
	</energy:outdoorShading>

	<energy:indoorShading>
		<energy:ShadingType>
			<energy:maximumCoverRatio uom="ratio">0.5</energy:maximumCoverRatio>
			<energy:name>Curtain</energy:name>
			<energy:transmittance>
				<energy:Transmittance>
					<energy:fraction uom="ratio">0.8</energy:fraction>
					<energy:wavelengthRange>Total</energy:wavelengthRange>
				</energy:Transmittance>
			</energy:transmittance>
		</energy:ShadingType>
	</energy:indoorShading>

	<energy:openableRatio uom="ratio">0.9</energy:openableRatio>

</bldg:Window>
```

364
### \_BoundarySurface, globalSolarIrradiance and daylightIlluminance
365

Esteban Munoz's avatar
Esteban Munoz committed
366
The CityGML abstract class `_BoundarySurface` is extended by a number of Energy
367
368
369
370
371
372
ADE attributes, in order to store construction information 
(`boundarySurfaceConstruction`) and refurbishment data 
(`refurbishmentMeasureOnBoundarySurface`). Via the general mechanism of attaching
time series of meteorological or radiation data to CityGML feature types, the 
incident global solar irradiances and the daylight illuminances can be related
with each outside boundary surface of the building. 
373

Esteban Munoz's avatar
Esteban Munoz committed
374
375
376
377
378
379
The `globalSolarIrradiance` is the sum of the direct, diffuse and reflected
irradiance incident on a outside boundary surface and is generally expressed in
Watts per square metre.  These global solar irradiance is generally used for
the thermal calculations within the buildings, but also for the calculation of
the energy yield produced by the solar systems (e.g. photovoltaic and solar
thermal panels).
380

Esteban Munoz's avatar
Esteban Munoz committed
381
The `daylightIlluminance` is the sum of the direct, diffuse and reflected solar
Esteban Munoz's avatar
Esteban Munoz committed
382
383
384
385
illuminance incident on a outside boundary surface. It is generally expressed
in Lux. Daylight illuminance is typically used for outside and inside
daylighting study, as well as the calculation of the energy consumptions of
lighting systems required to reach the room illuminance threshold when the
Esteban Munoz's avatar
Esteban Munoz committed
386
daylight illuminance is not enough.
Esteban Munoz's avatar
Esteban Munoz committed
387

388
389
```xml
<!--Example of a Roof object -->
390
<bldg:RoofSurface gml:id="id_roof_1">
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
   <gml:description>Description of Roof 1</gml:description>
   <gml:name>Name of Roof 1</gml:name>
   
   <energy:weatherData>
    <energy:WeatherData>
     <energy:weatherDataType>GlobalSolarIrradiance</energy:weatherDataType>
     <energy:values>
      <energy:RegularTimeSeries>
       <!-- Specification of the time series temporal extent and values (omitted here) -->
      </energy:RegularTimeSeries>
     </energy:values>
    </energy:WeatherData>    
   </energy:weatherData>
   
   
   <energy:weatherData>
    <energy:WeatherData>
     <energy:weatherDataType>DaylightIlluminance</energy:weatherDataType>
     <energy:values>
      <energy:RegularTimeSeries>
       <!-- Specification of the time series temporal extent and values (omitted here) -->
      </energy:RegularTimeSeries>
     </energy:values>
    </energy:WeatherData>    
   </energy:weatherData>   
   
   <energy:refurbishmentMeasureOnBoundarySurface>
    <energy:RefurbishmentMeasure>
     <!--Here come all attributes of a RefurbishmentMeasure object (omitted here)-->
    </energy:RefurbishmentMeasure>
   </energy:refurbishmentMeasureOnBoundarySurface>
    
  </bldg:RoofSurface>
424
425
```

RomainNouvel's avatar
RomainNouvel committed
426
427
## Thermal zones, thermal boundaries and thermal components

428
### ThermalZone
429

Esteban Munoz's avatar
Esteban Munoz committed
430
431
The `ThermalZone` is a new object introduced in the Energy ADE to realize
building heating and cooling demand calculation. A `ThermalZone` is a zone of a
432
`bldg:Building` (or of a `bldg:BuildingPart`) which serves as the smallest spatial zone
Esteban Munoz's avatar
Esteban Munoz committed
433
434
435
for building heating and cooling demand calculation. It is generally a "thermal
homogeneous" space considered as isothermal, but may also refer to several
building rooms and zones with different usage boundary conditions for
436
simplified building energy modelling.
Esteban Munoz's avatar
Esteban Munoz committed
437
438

A `ThermalZone` contains a series of energy-related attributes which
439
440
441
characterize its geometry (`floorArea`, `volume`,`volumeGeometry`), its conditioning 
status (`isCooled`, `isHeated`,`indirectlyHeatedAreaRatio`) and overall building 
physics properties (`additionalThermalBridgeUValue`, `infiltration rate`,
Esteban Munoz's avatar
Esteban Munoz committed
442
443
444
445
446
447
448
`effectiveThermalCapacity`).

All these attributes are optional. Among those, `floorArea` may be attributed
several times to a building, specifying different values for different
`FloorAreaType`. A `ThermalZone` may optionally contain an explicit volume
geometry (specified by `volumeGeometry`), useful in particular for
visualisation purposes, but not necessary for heating and cooling demand
449
calculations. The `ThermalZone` may also be related to a room (`bldg:Room`). The
Esteban Munoz's avatar
Esteban Munoz committed
450
actual surface boundaries of a `ThermalZone` are defined by means of
Esteban Munoz's avatar
Esteban Munoz committed
451
`ThermalBoudary` objects (see later).
452

Esteban Munoz's avatar
Esteban Munoz committed
453
454
455
456
457
458
459
If occupied, a `ThermalZone` must be related to at less one `UsageZone` object
(see Occupancy Module), which contains the usage boundary conditions for the
heating and cooling demand calculation (see Occupancy Module). `ThermalZone`
may even be related to several `UsageZone` for simplified modelling of
mixed-usage space, in which case the usage boundary conditions of the UsageZone
should be aggregated or weighted according with their `floorArea`.

Esteban Munoz's avatar
Esteban Munoz committed
460
The class `ThermalZone` inherits from `_CityObject`, and may therefore be
461
associated to one or more `EnergyDemand` objects (see module Energy Systems).
Esteban Munoz's avatar
Esteban Munoz committed
462
463
464

In the following, Two XML examples present a `ThermalZone`, with and without
explicit volume geometry.
465

466
```xml
467
<!--Example of a ThermalZone without explicit volume geometry-->
gioagu's avatar
gioagu committed
468
<energy:ThermalZone gml:id="id_thermalzone_1">
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
   <gml:description>Description of Thermal Zone 1</gml:description>
   <gml:name>Name of Thermal Zone 1</gml:name>
   <energy:additionalThermalBridgeUValue uom="W/(K*m^2)">0.5</energy:additionalThermalBridgeUValue>
   <energy:effectiveThermalCapacity uom="J/K">500</energy:effectiveThermalCapacity>
   <energy:floorArea>
    <energy:FloorArea>
     <energy:type>EnergyReferenceArea</energy:type>
     <energy:value uom="m^2">55.0</energy:value>
    </energy:FloorArea>
   </energy:floorArea>
   <energy:volume>
    <energy:VolumeType>
     <energy:type>GrossVolume</energy:type>
     <energy:value uom="m^3">200.0</energy:value>
    </energy:VolumeType>
   </energy:volume>
   
   <energy:volume>
    <energy:VolumeType>
     <energy:type>NetVolume</energy:type>
     <energy:value uom="m^3">180</energy:value>
    </energy:VolumeType>
   </energy:volume>
   
   <!-- here follows a related usage zone -->
   <energy:contains xlink:href="#id_usagezone_1"/>
   
   <energy:indirectlyHeatedAreaRatio uom="ratio">0.15</energy:indirectlyHeatedAreaRatio>
   <energy:infiltrationRate uom="1/h">1.2</energy:infiltrationRate>
   <energy:isCooled>true</energy:isCooled>
   <energy:isHeated>true</energy:isHeated>
   
   <!--Here follow all ThermalBoundary objects, each inside a "boundedBy" tag-->
   <energy:boundedBy>
    <energy:ThermalBoundary gml:id="id_thermalboundary_1">
     <!--Here come all attributes of the first ThermalBoundary (omitted here)-->
    </energy:ThermalBoundary>
   </energy:boundedBy>
   <energy:boundedBy>
    <energy:ThermalBoundary gml:id="id_thermalboundary_2">
     <!--Here come all attributes of the second ThermalBoundary (omitted here)-->
    </energy:ThermalBoundary>
   </energy:boundedBy>
   
  </energy:ThermalZone>
514
```
515

gioagu's avatar
gioagu committed
516
517
518
```xml
<!--Example of a ThermalZone with explicit volume geometry-->
<energy:ThermalZone gml:id="id_thermalzone_2">
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
   <!--Additional attributes of the ThermalZone (omitted here)-->
   
   <energy:isCooled>false</energy:isCooled>
   <energy:isHeated>true</energy:isHeated>
 
   <energy:volumeGeometry>
     <gml:Solid gml:id="id_thermalzone_volume_geometry_1" srsName="EPSG:31256" srsDimension="3">
     <gml:exterior>
      <gml:CompositeSurface>
       <gml:surfaceMember>
        <gml:Polygon>
         <gml:exterior>
          <gml:LinearRing>
           <gml:posList>0 0 0 0 10 0 5 10 0 5 0 0 0 0 0</gml:posList>
          </gml:LinearRing>
         </gml:exterior>
        </gml:Polygon>
       </gml:surfaceMember>
       <gml:surfaceMember>
        <gml:Polygon>
         <gml:exterior>
          <gml:LinearRing>
           <gml:posList>0 0 4 5 0 4 5 10 4 0 10 4 0 0 4</gml:posList>
          </gml:LinearRing>
         </gml:exterior>
        </gml:Polygon>
       </gml:surfaceMember>
       <!--Here come further surfaceMember objects-->
      </gml:CompositeSurface>
     </gml:exterior>
    </gml:Solid>
   </energy:volumeGeometry>
   
   <energy:boundedBy xlink:href="#ThermalBoundary_1"/>
  </energy:ThermalZone>
gioagu's avatar
gioagu committed
554
555
556
```

### ThermalBoundary
557

Esteban Munoz's avatar
Esteban Munoz committed
558
559
A `ThermalBoundary` represent the physical relationship between two
`ThermalZone`, or one `ThermalZone` and the building environment. Its
560
geometrical representation is a planar, or quasi planar, surface.
561

Esteban Munoz's avatar
Esteban Munoz committed
562
Each `ThermalZone` is geometrically closed by its whole set of bounding
563
564
565
566
567
568
569
570
`ThermalBoundary` (specificied in the relationship `boundedBy`).

A `ThermalBoundary` object must refer to its one or two corresponding 
`ThermalZone` objects via the relation `delimitsBy`. In case of an interior 
`ThermalBoundary`, the order of the two related `ThermalZone`objects is
significant. Because this order strongly depends on the order of the 
different material layers of the `ThermalBoundary`construction (`ThermalComponent`),
the rules determining the relation order are defined in the next section.
571

Esteban Munoz's avatar
Esteban Munoz committed
572
573
574
575
576
577
578
579
580
In the case where the `ThermalBoundary` delimits one `ThermalZone` from the
building environment, corresponding then to the external boundary of a
building, its geometrical representation coincides with the external surfaces
of the related outer wall/roof/basement floor. In this case, the
`ThermalBoundary` should be linked to the corresponding `_BoundarySurface`
object (e.g. a `WallSurface`, a `RoofSurface`, a `GroundSurface` in LoD2) if
existing, through the relationship "correspondsTo". It may however occurs that
such `ThermalBoundary` does not match with any `_BoundarySurface` (e.g.
basement ceiling, attic floor).
gioagu's avatar
gioagu committed
581

Esteban Munoz's avatar
Esteban Munoz committed
582
583
584
585
586
587
In the case where the `ThermalBoundary` separate two adjacent `ThermalZone`,
corresponding then to an intermediate floor, ceiling, or a shared wall, its
geometrical representation coincides with the plan laying at the middle of this
construction thickness.

The following figure represents these 2 different cases in a building side
Esteban Munoz's avatar
Esteban Munoz committed
588
section, relating the Energy ADE objects `ThermalZone` and `ThermalBoundary` to
Esteban Munoz's avatar
Esteban Munoz committed
589
the CityGML objects `Room` and `_BoundarySurface`.
590

591
![Schema of adjacent thermal zones](fig/ThermalZoneAdjacency.png)
592

593
`ThermalBoundary` may contain attributes characterizing their type  
594
595
596
597
598
(`thermalBoundaryType`), orientation (`azimuth` and `inclination`), size (`area`) 
and explicit geometry (`surfaceGeometry`). All these attributes are optional. 
Thus, a `ThermalZone` may optionally contain an explicit surface geometry 
(specified by `surfaceGeometry`), useful in particular for visualisation purposes 
if the `ThermalBoundary` does not coincide with any `_BoundarySurface`, but not
Esteban Munoz's avatar
Esteban Munoz committed
599
necessary for heating and cooling demand calculations.
RomainNouvel's avatar
RomainNouvel committed
600

Esteban Munoz's avatar
Esteban Munoz committed
601
602
603
The `ThermalBoundaryType` type is slightly different to the types of
`_BoundarySurface` from CityGML, integrating further thermal boundaries like
AtticFloor, BasementCeiling, BasementFloor or SharedWall.
RomainNouvel's avatar
RomainNouvel committed
604

605
606
607
Each `ThermalBoundary` is composed of `ThermalComponent` (e.g. wall
construction, windows etc.) which holds information on the corresponding material 
layers .
RomainNouvel's avatar
RomainNouvel committed
608

Esteban Munoz's avatar
Esteban Munoz committed
609
610
In the following, two XML examples of `ThermalBoundary`, with and without
explicit geometry are given.
RomainNouvel's avatar
RomainNouvel committed
611

gioagu's avatar
gioagu committed
612
```xml
RomainNouvel's avatar
RomainNouvel committed
613
<!--Example of a ThermalBoundary corresponding to a building roof, delimiting a thermal zone -->
gioagu's avatar
gioagu committed
614
<energy:ThermalBoundary gml:id="id_thermalboundary_1">
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
  <gml:description>Thermal Boundary 1</gml:description>
  <gml:name>Thermal Boundary 1</gml:name>
  <energy:thermalBoundaryType>Roof</energy:thermalBoundaryType>
  <energy:azimuth uom="deg">135</energy:azimuth>
  <energy:inclination uom="deg">55</energy:inclination> 
   
  <energy:composedOf>
    <energy:ThermalComponent gml:id="Thermalcomponent_1">
      <energy:area uom="m2">100</energy:area>
       <energy:construction xlink:href="#RoofConstruction"/>
    </energy:ThermalComponent>
  </energy:composedOf>
   
  <energy:composedOf>
    <energy:ThermalComponent gml:id="Thermalcomponent_2">
      <energy:area uom="m2">20</energy:area>
      <energy:construction xlink:href="#RoofWindowConstruction"/>
    </energy:ThermalComponent>
  </energy:composedOf>
   
  <energy:delimitsBy xlink:href="#AtticThermalZone"/>
   
 <energy:relatesTo xlink:href="#RoofSurface_1"/>
gioagu's avatar
gioagu committed
638
639
</energy:ThermalBoundary>
```
640

gioagu's avatar
gioagu committed
641
```xml
RomainNouvel's avatar
RomainNouvel committed
642
<!--Example of a ThermalBoundary with explicit surface geometry, separating two thermal zones -->
gioagu's avatar
gioagu committed
643
<energy:ThermalBoundary gml:id="id_thermalboundary_2">
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
 <!--Additional attributes of the ThermalBoundary class (omitted here)-->
   
  <energy:surfaceGeometry>
     <gml:MultiSurface gml:id="id_thermalboundary_2_surface_geometry" srsName="EPSG:31256" srsDimension="3">
       <gml:surfaceMember>
        <gml:Polygon>
          <gml:exterior>
            <gml:LinearRing>
              <gml:posList>0 0 0 0 10 0 5 10 0 5 0 0 0 0 0</gml:posList>
             </gml:LinearRing>
           </gml:exterior>
        </gml:Polygon>
       </gml:surfaceMember>
     </gml:MultiSurface>
  </energy:surfaceGeometry>
   
   <partOf xlink:href="#id_thermalzone_1"/>
   <partOf xlink:href="#id_thermalzone_2"/>
</energy:ThermalBoundary>  

gioagu's avatar
gioagu committed
664
```
665

gioagu's avatar
gioagu committed
666
### ThermalComponent
667

Esteban Munoz's avatar
Esteban Munoz committed
668
669
A `ThermalComponent` object is a part of the thermal boundary corresponding to
a homogeneous construction component (e.g. windows, wall, insulated part of a
670
wall etc.) and either entirely above or below the terrain. Each `ThermalComponent` 
671
must be characterized with its `area`, its position relative to the terrain 
672
673
(attribute `relativeToTerrain` which it inherits from `_CityObject`), and its
related `AbstractConstruction`(see Construction and Material module), defining the 
674
order of the `ThermalComponent's` different construction layers. This may be done
Esteban Munoz's avatar
Esteban Munoz committed
675
676
677
either inline or by means of xlinks (see example below). In this way,
`ThermalComponent` provides the physical properties of the building envelope to
calculate the heating and cooling demand.
678

679
680
681
682
683
The `ThermalComponent`objects thus define the construction layer order of a 
`ThermalBoundary` object. For simulating the energy transfer between two `ThermalZones`
or between a `ThermalZone` and the environment, it is essential to know which 
`ThermalZone`is in contact with which layer. This information is represented by the
order of the `ThermalZone` objects related with a `ThermalBoundary` (relation `delimitsBy`).
684
The order of the layers in the `AbstractConstruction` of a `ThermalComponent`
685
and the order of the related `ThermalZone` objects must obey the following rules:
686
687

- For exterior `ThermalBoundary` objects, the first layer is facing the exterior environment, and the last layer the building interior.
688
689
- For `ThermalBoundary` objects of type `IntermediaryFloor` or `BasementCeiling`, the first construction layer is facing the lower `ThermalZone` and the last layer the upper `ThermalZone`. The first relation `delimitsBy` points to the upper `ThermalZone`, and the last relation `delimitsBy` points to the lower `ThermalZone`.
- For all other interior `ThermalBoundary` objects, the first relation `delimitsBy` points to the `ThermalZone` facing the last construction layer, and the last relation `delimitsBy` points to the `ThermalZone` facing the first construction layer.
690

gioagu's avatar
gioagu committed
691
```xml
RomainNouvel's avatar
RomainNouvel committed
692
<!--Example of a Facade with 20% window to wall ratio -->
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
 <energy:ThermalBoundary gml:id="Id_Facade_1">
   <energy:thermalBoundaryType>OuterWall</energy:thermalBoundaryType>
   
   <energy:composedOf>
    <energy:ThermalComponent gml:id="id_Wall_1">
     <gml:description>Part of the facade of wall</gml:description>
     <core:relativeToTerrain>entirelyAboveTerrain</core:relativeToTerrain>
     <energy:area uom="m^2">120.0</energy:area>
     <energy:construction xlink:href="#id_WallConstruction_1"/>    
    </energy:ThermalComponent>
   </energy:composedOf>
   
   <energy:composedOf>
    <energy:ThermalComponent gml:id="id_Window_1">
     <gml:description>Part of the facade of windows</gml:description>
     <core:relativeToTerrain>entirelyAboveTerrain</core:relativeToTerrain>
     <energy:area uom="m^2">10.0</energy:area>
     <energy:relates xlink:href="#opening_window_1"/>
     <energy:construction xlink:href="#id_WindowConstruction_1"/>     
    </energy:ThermalComponent>
   </energy:composedOf>		
   
   <energy:delimitsBy xlink:href="#thermalZone_1"/>
   
  </energy:ThermalBoundary>
gioagu's avatar
gioagu committed
718
```
719

720
# Temporal Data Module
721

722
723
724
725
726
727
728
729
This module introduces the two new types `_TimeSeries` and `_Schedules`,
essential to model the time-depending inputs and results of urban energy
analyses. These types are used in other Modules of the Energy ADE, in
particular the module Occupancy and module Energy and Systems.

As theses types are actually not domain-specific, we are collaborating with the
development team of the CityGML 3.0 to integrate them in the new CityGML 3.0 to
come (as Dynamizer).
730

731
## Time Series
732

RomainNouvel's avatar
RomainNouvel committed
733
![Class diagram of ADE Energy Core - Time Series](fig/TimeSeries.png)
734

Esteban Munoz's avatar
Esteban Munoz committed
735
Time series are homogeneous lists of time-depending values. They are used in
Esteban Munoz's avatar
Esteban Munoz committed
736
737
738
739
740
the Energy ADE to store energy amount or an occupancy schedule, for instance. 

All time series share some common properties, gathered in the
`TimeValuesProperties` type object. This object specifies optionally the
`acquisitionMethod` (e.g. simulated with software X, measured with heat meter),
741
742
743
744
745
`interpolationType` (based on the [WaterML ADE][] to know for instance if
measured data are "Average in Preceding Interval", or "Instantaneous Total"),
`qualityDescription` and `source` of the time series data.
Additionally, `_TimeSeries`may contain the the usual GML type attributes `name`
and `description`.
Esteban Munoz's avatar
Esteban Munoz committed
746
747
748
749
750
751
752

Time series can be either regular or irregular. `RegularTimeSeries` contain
`values` generated at regularly spaced interval of time (`timeInterval`), over
a given `temporalExtent` (i.e. start, end and duration time). They are used,
for instance, to store automatically acquired data or hourly/daily/monthly
simulation results.
In `IrregularTimeSeries`, data follows a temporal sequence, but the measurement
753
754
points may not happen at a regular time interval ([IBM knowledge Center][]).
Therefore, each value must be associated with a data or time.
Esteban Munoz's avatar
Esteban Munoz committed
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769

Time series values may be also stored on an external file (e.g. csv or text),
both for regular (`RegularTimeSeriesFile`) and irregular time series
(`IrregularTimeSeriesFile`). A number of attributes must be detailed to
retrieve the `file`, interprete the formats and values inside it
(`decimalSymbol`, `recordSeparator`, `fieldSeparator`, `numberOfHeaderLines`,
`uom`), and know which values of the file should be read (`timeColumnNumber`
for irregular time series and `valueColumnNumber` for both of them). One file
with different records may be reused by different `RegularTimeSeriesFile` or
`IrregularTimeSeriesFile` with the corresponding `valueColumnNumber`.

In the following, four examples of time series illustrates the four types of
time series. The variableProperties and gml attributes are presented in the
first example but not always repeated in the following examples for better
readibility.
770

771
Example of RegularTimeSeries object:
772

gioagu's avatar
gioagu committed
773
```xml
774
<!--Example of RegularTimeSeries object with daily values-->
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
 <energy:RegularTimeSeries gml:id="id_timeseries_electricity_demand_1">
   <gml:description>Description of the time series id_timeseries_electricity_demand_1</gml:description>
   <gml:name>Name of the  time series id_timeseries_electricity_demand_1</gml:name>
   <energy:variableProperties>
    <energy:TimeValuesProperties>
     <energy:acquisitionMethod>Measurement</energy:acquisitionMethod>
     <energy:interpolationType>AverageInSucceedingInterval</energy:interpolationType>
     <energy:qualityDescription>Accurate (+/- 0.2 kWh)</energy:qualityDescription>
     <energy:source>Subcontracting company X</energy:source>
    </energy:TimeValuesProperties>
   </energy:variableProperties>
   <energy:temporalExtent>
    <gml:TimePeriod>
     <gml:beginPosition>2016-01-01</gml:beginPosition>
     <gml:endPosition>2016-12-31</gml:endPosition>
    </gml:TimePeriod>
   </energy:temporalExtent>
   <energy:timeInterval unit="day">1</energy:timeInterval>
   <energy:values uom="kWh">11.2 11.4 10.2 9.6 6.3 11.5 12.7 ... (truncated, set of 365 values) </energy:values>
  </energy:RegularTimeSeries>
gioagu's avatar
gioagu committed
795
```
796

797
Example of IrregularTimeSeries object:
gioagu's avatar
gioagu committed
798
```xml
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
<!--Example of IrregularTimeSeries object listing one value per year-->
<energy:IrregularTimeSeries gml:id="id_timeseries_electricity_demand_1">
	<energy:variableProperties>
		<energy:TimeValuesProperties>
			<energy:acquisitionMethod>Manual read on electrical meter</energy:acquisitionMethod>
			<energy:interpolationType>InstantTotal</energy:interpolationType>
		</energy:TimeValuesProperties>
	</energy:variableProperties>
	<energy:uom uom="kWh"/>
	<energy:contains>
		<energy:MeasurementPoint>
			<energy:time>2010-02-24</energy:time>
			<energy:value>12050</energy:value>
		</energy:MeasurementPoint>
	</energy:contains>
	<energy:contains>
		<energy:MeasurementPoint>
			<energy:time>2011-02-15</energy:time>
			<energy:value>14050</energy:value>
		</energy:MeasurementPoint>
	</energy:contains>
	<energy:contains>
		<energy:MeasurementPoint>
			<energy:time>2012-03-01</energy:time>
			<energy:value>16245</energy:value>
		</energy:MeasurementPoint>
	</energy:contains>
826
</energy:RegularTimeSeries>
gioagu's avatar
gioagu committed
827
```
828

829
Example of RegularTimeSeriesFile object:
gioagu's avatar
gioagu committed
830
```xml
831
832
833
<!--Example of RegularTimeSeriesFile object with hourly values contained in a file-->
<energy:RegularTimeSeriesFile gml:id="id_regulartimeseries_file_1">
	<energy:uom uom="W/m^2"/>
834
	<energy:file>file_name_containing_values.csv</energy:file>
835
836
	<energy:temporalExtent>
		<gml:TimePeriod>
837
838
			<gml:beginPosition>2008-01-01</gml:beginPosition>
			<gml:endPosition>2008-12-31</gml:endPosition>
839
840
841
842
843
844
845
		</gml:TimePeriod>
	</energy:temporalExtent>
	<energy:timeInterval unit="hour">1</energy:timeInterval>
	<energy:numberOfHeaderLines>1</energy:numberOfHeaderLines>
	<energy:valueColumnNumber>1</energy:valueColumnNumber>
	<energy:fieldSeparator>\t</energy:fieldSeparator>
</energy:RegularTimeSeriesFile>
gioagu's avatar
gioagu committed
846
```
847

848
Example of IrregularTimeSeriesFile object:
gioagu's avatar
gioagu committed
849
```xml
850
851
852
853
854
855
856
857
858
859
860
<!--Example of IrregularTimeSeriesFile object-->
<energy:RegularTimeSeriesFile gml:id="id_regulartimeseries_file_1">
	<energy:uom uom="W/m^2"/>
	<energy:file>file_name_containing_values.csv</energy:file>
	<energy:numberOfHeaderLines>1</energy:numberOfHeaderLines>
	<energy:recordSeparator> </energy:recordSeparator>
	<energy:decimalSymbol>,</energy:decimalSymbol>
	<energy:valueColumnNumber>9</energy:valueColumnNumber>
	<energy:timeColumnNumber>1</energy:timeColumnNumber>
	<energy:fieldSeparator>\t</energy:fieldSeparator>
</energy:RegularTimeSeriesFile>
gioagu's avatar
gioagu committed
861
```
862

863
## Schedules
864

RomainNouvel's avatar
RomainNouvel committed
865
![Class diagram of ADE Energy Core - Schedules](fig/Schedules.png)
866

Esteban Munoz's avatar
Esteban Munoz committed
867
868
869
870
871
872
873
874
875
The type `_Schedule` is used in the Energy ADE for different kinds of schedules
related to the building usage: heating and cooling schedules (set-point
temperatures), ventilation schedules (mechanical air change rate), occupancy
rate and facilities operation schedules.

Schedules can be modelled in 4 possible "semantic levels of detail", depending
on the available information and the application requirements. These levels of
detail range from a simple constant value to a detailed schedule characterised
by a `_TimeSeries` object.
876

877
### ConstantValueSchedule
878

Esteban Munoz's avatar
Esteban Munoz committed
879
880
The simplest level of detail, this Schedule is defined by a constant measure
(`averageValue`), generally corresponding to the average parameter value.
881
882

```xml
883
884
885
886
<!--Example of a ConstantValueSchedule-->
<energy:ConstantValueSchedule gml:id="id_constant_schedule_1">
	<energy:averageValue uom="degree Celsius">26</energy:averageValue>
</energy:ConstantValueSchedule>
887
888
```

889
### DualValueSchedule
890

Esteban Munoz's avatar
Esteban Munoz committed
891
892
893
894
895
896
A two-state schedule. This schedule is defined by a `usageValue` for usage
times, and an `idleValue` outside these temporal boundaries. Usage times are
characterized by the numbers `usageHoursPerDay` and `usageHoursPerDay` (usage
hours per usage days). This schedule complies in particular with the data
requirements of the codes and norms describing the monthly energy balance (DIN
18599-2, ISO 13790).
897

898
```xml
899
<!--Example of a DualValueSchedule-->
gioagu's avatar
Typo    
gioagu committed
900
<energy:DualValueSchedule gml:id="id_dualvalue_schedule_2">
901
902
903
904
905
	<energy:usageValue uom="degree Celsius">20</energy:usageValue>
	<energy:idleValue uom="degree Celsius">16</energy:idleValue>
	<energy:usageHoursPerDay uom="hour">17</energy:usageHoursPerDay>
	<energy:usageDaysPerYear uom="day">365</energy:usageDaysPerYeary>
</energy:DualValueSchedule>
906
907
```

908
### DailyPatternSchedule
909

910
911
912
This more detailed schedule is composed of one or more `periodOfYear`, being itself
composed of `dailySchedule` associated to recurrent `dayType` (e.g. weekday, weekend). 
These daily schedules are of type` _TimeSeries`, as described above.
913
914
915

```xml
<!--Example of a daily pattern schedule for a standard week composed of weekday and weekend days-->
916
<energy:DailyPatternSchedule gml:id="id_dailypattern_schedule_3">
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
  <energy:periodOfYear>
   <energy:PeriodOfYear>
    <energy:period>
     <gml:TimePeriod>
      <gml:beginPosition>2015-01-01</gml:beginPosition>
      <gml:endPosition>2015-12-31</gml:endPosition>
     </gml:TimePeriod>
    </energy:period>
    
    <energy:dailySchedule>
     <energy:DailySchedule>
      <energy:dayType>WeekDay</energy:dayType>
      <energy:schedule>
       <energy:RegularTimeSeries gml:id="id_cooling_daily_timeseries_1">
        <energy:variableProperties>
         <energy:TimeValuesProperties>
          <energy:acquisitionMethod>Estimation</energy:acquisitionMethod>
          <energy:interpolationType>Continuous</energy:interpolationType>
         </energy:TimeValuesProperties>
        </energy:variableProperties>
        <energy:temporalExtent>
         <gml:TimePeriod>
          <gml:beginPosition>00:00:00</gml:beginPosition>
          <gml:endPosition>23:59:59</gml:endPosition>
         </gml:TimePeriod>
        </energy:temporalExtent>
        <energy:timeInterval unit="hour">1</energy:timeInterval>
        <energy:values uom="C">25 25 25 25 25 25 25 20 20 20 20 20
               20 20 20 20 20 20 20 25 25 25 25 25</energy:values>
       </energy:RegularTimeSeries>
      </energy:schedule>
     </energy:DailySchedule>
    </energy:dailySchedule>
    
    <energy:dailySchedule>
     <energy:DailySchedule>
      <energy:dayType>WeekEnd</energy:dayType>
      <energy:schedule>
       <energy:RegularTimeSeries gml:id="id_cooling_daily_timeseries2">
        <energy:variableProperties>
         <energy:TimeValuesProperties>
          <energy:acquisitionMethod>Estimation</energy:acquisitionMethod>
          <energy:interpolationType>Continuous</energy:interpolationType>
         </energy:TimeValuesProperties>
        </energy:variableProperties>
        <energy:temporalExtent>
         <gml:TimePeriod>
          <gml:beginPosition>00:00:00</gml:beginPosition>
          <gml:endPosition>23:59:59</gml:endPosition>
         </gml:TimePeriod>
        </energy:temporalExtent>
        <energy:timeInterval unit="hour">1</energy:timeInterval>
        <energy:values uom="C">25 25 25 25 25 25 25 25 25 20 20 20
               20 20 20 20 20 20 20 20 20 20 25 25</energy:values>
       </energy:RegularTimeSeries>
      </energy:schedule>
     </energy:DailySchedule>
    </energy:dailySchedule>
    
   </energy:PeriodOfYear>
  </energy:periodOfYear>       
978
979
980
</energy:DailyPatternSchedule>
```

981
### TimeSeriesSchedule
982

Esteban Munoz's avatar
Esteban Munoz committed
983
984
This type is the most detailed of all `_schedule` levels of details. It
consists of a unique time series, without patterns.
985

986
987
```xml
<!--Example of a time series based schedule with hourly values for one year-->
988
989
<energy:TimeSeriesSchedule gml:id="id_timeseries_schedule_4">
	<energy:RegularTimeSeries "id_occupants_timeseries4">
990
991
992
993
994
995
996
997
998
999
1000
1001
			<energy:temporalExtent>
				<gml:TimePeriod>
					<gml:beginPosition>2000-01-01</gml:beginPosition>
					<gml:endPosition>2000-12-31</gml:endPosition>
				</gml:TimePeriod>
			</energy:temporalExtent>
			<energy:timeInterval unit="hour">1</energy:timeInterval>
			<energy:values uom="ratio">1 1 1 1 0.9 0.7 0.5 ... (truncated, set of 8760 values)</energy:values>
	</energy:RegularTimeSeries>
</energy:TimeSeriesSchedule>
```

1002
# Construction and Material Module
1003

RomainNouvel's avatar
RomainNouvel committed
1004
![Class diagram of Construction Module](fig/Construction.png)
1005

Esteban Munoz's avatar
Esteban Munoz committed
1006
1007
1008
The Construction and Material module of the ADE Energy characterizes physically
the building construction parts, detailing their structure and specifiying
their thermal and optical properties. 
1009

1010
1011
1012
1013
1014
The central feature type of the module is `Construction`, which may either be used 
directly or as `ReverseConstruction`, modelling a `baseConstruction` with 
inverted order of layers. The abstract feature type `AbstracConstruction`, being
used in `ThermalComponent` and in extended properties of `_BoundarySurface`and
`_Opening`, is the common super class of `Construction`and `ReverseConstruction`.
1015

Esteban Munoz's avatar
Esteban Munoz committed
1016
## Construction
1017

Esteban Munoz's avatar
Esteban Munoz committed
1018
1019
This is the central object of this module, which holds the physical
characterisation of building envelop or intern room partition (e.g. wall, roof,
1020
1021
openings). Each `Construction` object may be characterised by optical and/or 
physical properties.
Esteban Munoz's avatar
Esteban Munoz committed
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057

The `OpticalProperties` type specified the `emissivity`, `reflectance`,
`transmittance` and `glazingRatio` of the construction and its surfaces:

- *Emissivity* is the ratio of the infrared (also called long-wave) radiation
  emitted by a specific surface/object to that of a black body. It is specified
  for a given surface (`SurfaceSide`). According with the Kirchoff and Lambert
  law, for a diffuse grey body the aborptance and the emittance are equal for a
  given wavelength range.

- *Reflectance* is the fraction of incident radiation which is reflected by an
  object. It is specified for a given surface (`SurfaceSide`) and for a given
  `wavelengthRange` type ("Visible", "Infrared", "Solar" or "Total" spectrums).

- *Transmittance* is the fraction of incident radiation which passes through a
  specific object. It is specified for a given `wavelengthRange` type . For
  example, the total transmittance of a window correspond to its *g-value*
  (also called Solar Heat Gain Coefficient). The transmittance value is
  included between 0 (completely opaque object) and 1 (completely transparent
  object).

- the `glazingRatio` corresponds of to proportion of the construction surface
  which is transparent and for which the transmittance is defined. For the
  modelling of window, `glazingRatio` corresponds to the proportion of window
  surface not cover by the window frame.

The thermal properties of the Construction may be characterized with two
possible "levels of details" : either with the heat transmission coefficient
`uValue` for steady-state thermal modelling, or by detailing its different
`Layer` of materials and their thermal behaviour.

In this last case, the `Construction` may be defined as an ordered combination
of `Layer`, containing possibly several `LayerComponent` made of materials.

In the following, several examples of Construction objects are presented, with
different levels of complexity.
gioagu's avatar
gioagu committed
1058

1059
A simple wall characterised with its U-value :
gioagu's avatar
gioagu committed
1060
1061

```xml
1062
1063
1064
1065
1066
<!--Example of a wall construction simply characterised with a U-value-->
<energy:Construction gml:id="id_construction_1">
	<gml:description>Description of Construction 1</gml:description>
	<gml:name>Name of Construction 1</gml:name>
	<energy:uValue uom="W/(K*m^2)">1.2</energy:uValue>
gioagu's avatar
gioagu committed
1067
1068
1069
</energy:Construction>
```

Esteban Munoz's avatar
Esteban Munoz committed
1070
1071
1072
A window characterised with its U-value, its emissivity, its g-value and its
visible transmittance.

gioagu's avatar
gioagu committed
1073
```xml
1074
<!--Example of low-emissivity window Construction object-->
gioagu's avatar
gioagu committed
1075
1076
1077
1078
1079
1080
<energy:Construction gml:id="id_construction_2">
	<gml:description>Description of the windows Construction</gml:description>
	<gml:name>Name of the window Construction</gml:name>
	<energy:uValue uom="W/(K*m^2)">1.9</energy:uValue>
	<energy:opticalProperties>
		<energy:OpticalProperties>
1081
			<energy:emissivity>
1082
				<energy:Emissivity>
1083
1084
					<energy:fraction uom="ratio">0.04</energy:fraction>
					<energy:surface>Inside</energy:surface>
1085
				</energy:Emissivity>
1086
			</energy:emissivity>
1087
			<!-- Here follows the g-value (or SHGC) characterization-->
gioagu's avatar
gioagu committed
1088
1089
			<energy:transmittance>
				<energy:Transmittance>
1090
1091
1092
1093
1094
1095
1096
1097
1098
					<energy:fraction uom="ratio">0.65</energy:fraction>
					<energy:wavelengthRange>Total</energy:wavelengthRange>
				</energy:Transmittance>
			</energy:transmittance>
			<!-- Here follows the visible transmittance characterization-->
			<energy:transmittance>
				<energy:Transmittance>
					<energy:fraction uom="ratio">0.55</energy:fraction>
					<energy:wavelengthRange>Visible</energy:wavelengthRange>
gioagu's avatar
gioagu committed
1099
1100
				</energy:Transmittance>
			</energy:transmittance>
1101
			<energy:glazingRatio uom="ratio">0.8</energy:glazingRatio>
gioagu's avatar
gioagu committed
1102
1103
1104
1105
		</energy:OpticalProperties>
	</energy:opticalProperties>
</energy:Construction>
```
1106

1107
### ReverseConstruction
1108

1109
1110
1111
This class defines a `Construction` object with reverted layer order. This may be necesssary
because the same construction, if common to different zones or buildings, might be orientated
in two different directions.
1112

gioagu's avatar
gioagu committed
1113
1114
```xml
<!--Example of ConstructionOrientation object-->
1115
1116
1117
1118
1119
<energy:ReverseConstruction>
   <gml:description>Description of a reverted Construction</gml:description>
   <energy:baseConstruction xlink:href="#id_construction_1"/>
  </energy:ReverseConstruction>
 </gml:featureMember>
gioagu's avatar
gioagu committed
1120
```
1121

RomainNouvel's avatar
RomainNouvel committed
1122
## Layers and layer components
1123

Esteban Munoz's avatar
Esteban Munoz committed
1124
1125
1126
1127
A `Construction` may be defined as an ordered combination of layers, themselves
composed of one or more `LayerComponent`.
A `LayerComponent` is a homogeneous part of a `Layer` (composed of a unique
material) covering a given fraction (`areaFraction`) of it.
1128

Esteban Munoz's avatar
Esteban Munoz committed
1129
1130
The materials of each `LayerComponent` may be specified either inline or by
means of xlinks (more adapted to materials  reused in different constructions).
1131

Esteban Munoz's avatar
Esteban Munoz committed
1132
1133
1134
1135
The XML example below characterizes a insulated outer wall construction with
three layers.
The materials are referenced with xlinks (the material characterization of
ID_Material_Concrete follows in the paragrap Material).
1136

Esteban Munoz's avatar
Esteban Munoz committed
1137
```xml                   
Joachim Benner's avatar
Joachim Benner committed
1138
1139
<!--Example of a three layered construction-->
<energy:Construction gml:id="ThreeLayeredMaterial">
1140

1141
1142
1143
1144
 <energy:layer>
  <energy:Layer>
   <energy:layerComponent>
    <energy:LayerComponent>
1145
1146
     <energy:thickness uom="m">0.12</energy:thickness>
     <energy:material xlink:href="#ID_Material_Polyurethan"/>
1147
1148
    </energy:LayerComponent>
   </energy:layerComponent>
1149
1150
1151
1152
1153
  </energy:Layer>
 </energy:layer>
 
  <energy:layer>
  <energy:Layer>
1154
1155
1156
1157
1158
1159
   <energy:layerComponent>
    <energy:LayerComponent>
     <energy:thickness uom="m">0.24</energy:thickness>
     <energy:material xlink:href="#ID_Material_Concrete"/>
    </energy:LayerComponent>
   </energy:layerComponent>
1160
1161
1162
1163
1164
  </energy:Layer>
 </energy:layer>
 
 <energy:layer>
  <energy:Layer>
1165
1166
   <energy:layerComponent>
    <energy:LayerComponent>
1167
1168
     <energy:thickness uom="m">0.02</energy:thickness>
     <energy:material xlink:href="#ID_Material_Plasterboard"/>
1169
1170
1171
1172
    </energy:LayerComponent>
   </energy:layerComponent>
  </energy:Layer>
 </energy:layer>
1173

Joachim Benner's avatar
Joachim Benner committed
1174
1175
1176
</energy:Construction>
```

1177
![Three layer Construction](fig/ThreeLayerConstruction.png)
1178
1179
1180
1181
1182

## Materials

### AbstractMaterial

Esteban Munoz's avatar
Esteban Munoz committed
1183
1184
1185
`_AbstractMaterial` is the abstract superclass for all Material classes. A
Material is a homogeneous substance. We distinguish solid materials (with mass)
from gas (without mass).
1186
1187
1188

### SolidMaterial

Esteban Munoz's avatar
Esteban Munoz committed
1189
1190
`SolidMaterial` is the class of materials which have a mass and a heat
capacity.
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203

```xml
<!-- Characterisation of the material Concrete-->
<energy:material gml = "ID_Material_Concrete">
        <energy:SolidMaterial>
                <gml:name>Concrete 2100</gml:name>
                <energy:conductivity uom="W/(K*m^2)">2.035</energy:conductivity>
                <energy:density uom="kg/m^3">2100.0</energy:density>
                <energy:specificHeat uom="J/(K*kg)">920.0</energy:specificHeat>
        </energy:SolidMaterial>
</energy:material>
```
 
1204
### Gas
1205

Esteban Munoz's avatar
Esteban Munoz committed
1206
`Gas` is the class of materials whose mass and heat capacity are neglectable in
Esteban Munoz's avatar
Esteban Munoz committed
1207
comparison with `SolidMaterial`.
1208

Joachim Benner's avatar
Joachim Benner committed
1209
```xml
gioagu's avatar
gioagu committed
1210
<!--Example of a gas material with neglectable mass and heat capacity-->
1211
1212
1213
1214
1215
1216
1217
<energy:material>
	<energy:Gas>
		<gml:name>non-ventilated air gap</gml:name>
		<energy:isVentilated>false</energy:isVentilated>
		<energy:rValue uom="K*m^2/W">4.5</energy:rValue>
	</energy:Gas>
</energy:material>
Joachim Benner's avatar
Joachim Benner committed
1218
1219
```

1220
# Occupancy Module
1221

RomainNouvel's avatar
RomainNouvel committed
1222
![Class diagram of Occupancy Module](fig/Occupancy_withoutCodelist.png)
RomainNouvel's avatar
RomainNouvel committed
1223
1224

...and its enumeration and codelists
RomainNouvel's avatar
RomainNouvel committed
1225
![Codelists of Occupancy Module](fig/Occupancy_OnlyCodelists.png)
1226

Esteban Munoz's avatar
Esteban Munoz committed
1227
The Occupancy Module contains the detailed characterization of the building
1228
1229
1230
1231
1232
usage, it means the people and the facilities. It is related to the rest of the
ADE Energy and CityGML model through the class `UsageZone`.
One building may have several `UsageZone`. Due to the type of information it
allows to store, the Occupancy Module may be used also for multi-field analysis
(socio-economics, demographics etc.).
1233

RomainNouvel's avatar
RomainNouvel committed
1234
1235
## Usage zones and building units

1236
1237
`UsageZone` and `BuildingUnit` are the two occupancy-related spatial partitions of a building in the CityGML Energy ADE.
A mixed-use building will be modelled with several `UsageZone`. Each of this `UsageZone` may contain several `BuildingUnit`, related to the premises (dwellings, offices etc.) located inside the defined `UsageZone`.
1238

1239
1240
The picture below illustrates this concept, showing a mixed-use building corresponding to a single Building entity in a CityGML model file (although several real adresses).
It consists in 3 different uses : company office on the first floor at the left of the main entrance, residential on the first floor in the opposite side of the building, and a post office covering the whole ground floor and the part of the first floor just above the main entrance ("Post"). Both `UsageZone` of type office and residential have two `BuildingUnit`, corresponding to different private offices ("O1" and "O2"), respectively different dwellings ("D1" and "D2").
1241
1242
1243

![3D representation of mixed-use building](fig/UsageZoneBuildingUnitExample.png)

1244
The CityGML+Energy ADE model of this example is detailed below:
1245
1246
```xml
<!--mixed-use building example-->
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
<bldg:Building gml:id="ExampleMixedUseBuilding">
	<energy:usageZones>
		<energy:UsageZone gml:id="Post">
			<energy:usageZoneClass>Post office</energy:usageZoneClass>
			<!-- Further attributes of usage zone "Post-Office" -->
		</energy:UsageZone>
	</energy:usageZones>
	<energy:usageZones>
		<energy:UsageZone gml:id="Offices">
			<energy:usageZoneClass>Company office</energy:usageZoneClass>
			<!-- Further attributes of usage zone "Offices" -->
			<energy:contains>
				<energy:BuildingUnit gml:id="O1">
					<!-- Further attributes of building unit "O1" -->	
				</energy:BuildingUnit>
			</energy:contains>
			<energy:contains>
				<energy:BuildingUnit gml:id="O2">
					<!-- Further attributes of building unit "O2" -->	
				</energy:BuildingUnit>
			</energy:contains>
		</energy:UsageZone>
	</energy:usageZones>
	<energy:usageZones>
		<energy:UsageZone gml:id="Dwellings">
			<energy:usageZoneClass>residential</energy:usageZoneClass>
			<!-- Further attributes of usage zone "Dwellings" -->
			<energy:contains>
				<energy:BuildingUnit gml:id="D1">
					<!-- Further attributes of building unit "D1" -->	
				</energy:BuildingUnit>
			</energy:contains>
			<energy:contains>
				<energy:BuildingUnit gml:id="D2">
					<!-- Further attributes of building unit "D2" -->	
				</energy:BuildingUnit>
			</energy:contains>
		</energy:UsageZone>
	</energy:usageZones>
</bldg:Building>
1287
1288
```

RomainNouvel's avatar
RomainNouvel committed
1289
### UsageZone
1290

1291
1292
1293
1294
1295
1296
The `UsageZone` is a new object introduced in the Energy ADE to realize
building usage analyses, and in particular to calculate the energy demand
related to occupant-depending end-uses such as domestic hot water, electrical
appliances, cooking etc. When related to the `ThermalZone`, it allows also to
provide the zone usage conditions (e.g. internal gains, HVAC schedules) for the
space heating and cooling demand calculations.
1297

1298
1299
1300
1301
`UsageZone` is a zone of a `Building` (or of a `BuildingPart`) with homogeneous
usage conditions and indoor climate control settings. It is a semantic object,
with an optional geometry (`volumeGeometry`), which may be or not related to a
geometric entity (Building, BuildingPart, Room etc.).
1302

1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
`UsageZone` is minimally defined by the two mandatory attributes
`usageZoneClass` (its usage type according to the CityGML Code list of the
`_AbstractBuilding` attribute `class`) and `floorArea`. The latter may be
attributed several times to a building, specifying different values for
different `FloorAreaType`.
Its HVAC schedules are characterized by the optional attributes
`heatingSchedule`, `coolingSchedule` and `ventilationSchedule` (respectively
for the heating and cooling set-point temperature schedules, and air
ventilation schedules). Alternatively to the `volumeGeometry` attribute, the
building storeys occupied by this `UsageZone` may be also indicated by means of
the attribute `usedFloors` (0 corresponding to the ground floor).
Its optional `internalGains` attribute corresponds to the sum of the energy
dissipated from the occupants and the facilities inside the zone.

The following XML example describe the modeling of a mixed-usage building.
1318

1319
```xml
gioagu's avatar
gioagu committed
1320
1321
1322
1323
1324
1325
1326
1327
<!--Example of a UsageZone-->
<energy:UsageZone gml:id="id_usagezone_1">
	<gml:description>Description of UsageZone 1</gml:description>
	<gml:name>Name of UsageZone 1</gml:name>
	<energy:usageZoneClass>Commercial</energy:usageZoneClass>
	<energy:usedFloors>1</energy:usedFloors>
	<energy:floorArea>
		<energy:FloorArea>
1328
			<energy:type>NetFloorArea</energy:type>
gioagu's avatar
gioagu committed
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357