0
# Building Model Classes
1

2
Core classes for creating and managing building energy models with hierarchical object relationships and template-based type safety. The model module provides hundreds of building component classes organized in a comprehensive object-oriented framework.
3

4
## Capabilities
5

6
### Model Container
7

8
The primary container class for all building model objects, providing template-based access and lifecycle management.
9

10
```cpp { .api }
11
/**
12
 * Primary container class for all building model objects
13
 * Inherits from Workspace and adds building-specific functionality
14
 */
15
class Model : public openstudio::Workspace {
16
public:
17
  // Constructors
18
  Model();
19
  Model(const IdfFile& idfFile);
20
  Model(const Workspace& workspace);
21

22
  // Template-based object access
23
  template<typename T>
24
  boost::optional<T> getModelObject(const Handle& handle) const;
25
  
26
  template<typename T>
27
  std::vector<T> getConcreteModelObjects() const;
28
  
29
  template<typename T>
30
  T getUniqueModelObject();
31
  
32
  template<typename T>
33
  boost::optional<T> getOptionalUniqueModelObject();
34
  
35
  template<typename T>
36
  std::vector<T> getModelObjectsByName(const std::string& name) const;
37
  
38
  template<typename T>
39
  boost::optional<T> getModelObjectByName(const std::string& name) const;
40

41
  // Simulation output connection
42
  boost::optional<SqlFile> sqlFile() const;
43
  bool setSqlFile(const SqlFile& sqlFile);
44
  void resetSqlFile();
45

46
  // Component operations
47
  ComponentData insertComponent(const Component& component);
48
  void purgeUnusedResourceObjects();
49
  
50
  // HVAC system connections
51
  bool connect(ModelObject sourceObject, 
52
               unsigned sourcePort,
53
               ModelObject targetObject, 
54
               unsigned targetPort);
55
  void disconnect(ModelObject object, unsigned port);
56
  
57
  // Autosizing operations
58
  void autosize();
59
  void applySizingValues();
60
  
61
  // Cached unique objects (automatically created as needed)
62
  Building building() const;
63
  Site site() const;
64
  SimulationControl simulationControl() const;
65
  WeatherFile weatherFile() const;
66
  Timestep timestep() const;
67
  RunPeriod runPeriod() const;
68
};
69
```
70

71
**Usage Examples:**
72

73
```cpp
74
#include <openstudio/model/Model.hpp>
75
#include <openstudio/model/Zone.hpp>
76
#include <openstudio/model/Building.hpp>
77

78
// Create new model
79
Model model;
80

81
// Access unique objects (created automatically)
82
Building building = model.building();
83
building.setName("Office Building");
84

85
// Create and access multiple objects
86
Zone zone1(model);
87
Zone zone2(model);
88
std::vector<Zone> allZones = model.getConcreteModelObjects<Zone>();
89

90
// Template-based access with handles
91
Handle zoneHandle = zone1.handle();
92
boost::optional<Zone> foundZone = model.getModelObject<Zone>(zoneHandle);
93

94
// Access by name
95
zone1.setName("Main Zone");
96
boost::optional<Zone> namedZone = model.getModelObjectByName<Zone>("Main Zone");
97
```
98

99
### ModelObject Base Class
100

101
Base class for all building model objects providing common functionality and resource management.
102

103
```cpp { .api }
104
/**
105
 * Base class for all building model objects
106
 * Provides common functionality for hierarchy, resources, and metadata
107
 */
108
class ModelObject : public openstudio::WorkspaceObject {
109
public:
110
  virtual ~ModelObject() = default;
111

112
  // Object lifecycle
113
  ModelObject clone(Model model) const;
114
  Component createComponent() const;
115
  
116
  // Model access
117
  Model model() const;
118
  
119
  // Object hierarchy
120
  boost::optional<ParentObject> parent() const;
121
  bool setParent(ParentObject& newParent);
122
  std::vector<ModelObject> children() const;
123
  
124
  // Resource management
125
  std::vector<ResourceObject> resources() const;
126
  std::vector<ModelObject> getModelObjectSources() const;
127
  
128
  template<typename T>
129
  std::vector<T> getModelObjectSources() const;
130
  
131
  template<typename T>
132
  boost::optional<T> getModelObjectTarget(unsigned index) const;
133
  
134
  template<typename T>
135
  std::vector<T> getModelObjectTargets() const;
136

137
  // Simulation output
138
  std::vector<std::string> outputVariableNames() const;
139
  std::vector<OutputVariable> outputVariables() const;
140
  
141
  // Economic analysis
142
  std::vector<LifeCycleCost> lifeCycleCosts() const;
143
  boost::optional<LifeCycleCost> createLifeCycleCost(
144
    const std::string& name,
145
    const std::string& category,
146
    double cost);
147

148
  // Metadata and properties
149
  AdditionalProperties additionalProperties() const;
150
  
151
  // EnergyManagementSystem integration
152
  std::vector<std::string> emsActuatorNames() const;
153
  std::vector<std::string> emsInternalVariableNames() const;
154
};
155
```
156

157
### Building Geometry Objects
158

159
Core geometric objects representing the building envelope and spatial organization.
160

161
```cpp { .api }
162
/**
163
 * Building object - overall building properties
164
 */
165
class Building : public ParentObject {
166
public:
167
  Building(const Model& model);
168
  
169
  // Geometric properties
170
  boost::optional<double> northAxis() const;
171
  bool setNorthAxis(double northAxis);
172
  
173
  boost::optional<double> nominalFloortoFloorHeight() const;
174
  bool setNominalFloortoFloorHeight(double nominalFloortoFloorHeight);
175
  
176
  // Floor area calculations
177
  boost::optional<double> floorArea() const;
178
  boost::optional<double> conditionedFloorArea() const;
179
  
180
  // Building stories
181
  std::vector<BuildingStory> buildingStories() const;
182
  
183
  // Spaces and zones
184
  std::vector<Space> spaces() const;
185
  std::vector<ThermalZone> thermalZones() const;
186
};
187

188
/**
189
 * BuildingStory - floor/story organization
190
 */
191
class BuildingStory : public ParentObject {
192
public:
193
  BuildingStory(const Model& model);
194
  
195
  boost::optional<double> nominalZCoordinate() const;
196
  bool setNominalZCoordinate(double nominalZCoordinate);
197
  
198
  boost::optional<double> nominalFloortoFloorHeight() const;
199
  bool setNominalFloortoFloorHeight(double nominalFloortoFloorHeight);
200
  
201
  std::vector<Space> spaces() const;
202
};
203

204
/**
205
 * Space - architectural space representation
206
 */
207
class Space : public ParentObject {
208
public:
209
  Space(const Model& model);
210
  
211
  // Geometry
212
  boost::optional<double> directionofRelativeNorth() const;
213
  bool setDirectionofRelativeNorth(double directionofRelativeNorth);
214
  
215
  boost::optional<double> xOrigin() const;
216
  boost::optional<double> yOrigin() const; 
217
  boost::optional<double> zOrigin() const;
218
  bool setXOrigin(double xOrigin);
219
  bool setYOrigin(double yOrigin);
220
  bool setZOrigin(double zOrigin);
221
  
222
  // Floor area and volume
223
  boost::optional<double> floorArea() const;
224
  boost::optional<double> volume() const;
225
  
226
  // Surfaces and subsurfaces
227
  std::vector<Surface> surfaces() const;
228
  
229
  // Thermal zone connection
230
  boost::optional<ThermalZone> thermalZone() const;
231
  bool setThermalZone(ThermalZone& thermalZone);
232
  void resetThermalZone();
233
  
234
  // Space type and loads
235
  boost::optional<SpaceType> spaceType() const;
236
  bool setSpaceType(const SpaceType& spaceType);
237
  
238
  std::vector<People> people() const;
239
  std::vector<Lights> lights() const;
240
  std::vector<ElectricEquipment> electricEquipment() const;
241
};
242

243
/**
244
 * ThermalZone - thermal zone for HVAC
245
 */
246
class ThermalZone : public ParentObject {
247
public:
248
  ThermalZone(const Model& model);
249
  
250
  // Thermostat control
251
  boost::optional<ThermostatSetpointDualSetpoint> thermostatSetpointDualSetpoint() const;
252
  bool setThermostatSetpointDualSetpoint(const ThermostatSetpointDualSetpoint& thermostat);
253
  
254
  // Zone equipment
255
  std::vector<ModelObject> equipment() const;
256
  bool addEquipment(const ModelObject& equipment);
257
  bool removeEquipment(const ModelObject& equipment);
258
  
259
  // Air loop connections
260
  boost::optional<AirLoopHVAC> airLoopHVAC() const;
261
  
262
  // Spaces in zone
263
  std::vector<Space> spaces() const;
264
  
265
  // Zone sizing
266
  SizingZone sizingZone() const;
267
};
268
```
269

270
### Surface and Construction Objects
271

272
Objects representing building envelope components and their thermal properties.
273

274
```cpp { .api }
275
/**
276
 * Surface - walls, floors, roofs, internal surfaces
277
 */
278
class Surface : public ParentObject {
279
public:
280
  Surface(const std::vector<Point3d>& vertices, const Model& model);
281
  
282
  // Surface properties
283
  std::string surfaceType() const;
284
  bool setSurfaceType(const std::string& surfaceType);
285
  
286
  std::string outsideBoundaryCondition() const;
287
  bool setOutsideBoundaryCondition(const std::string& outsideBoundaryCondition);
288
  
289
  // Geometry
290
  std::vector<Point3d> vertices() const;
291
  bool setVertices(const std::vector<Point3d>& vertices);
292
  
293
  double grossArea() const;
294
  double netArea() const;
295
  
296
  boost::optional<double> tilt() const;
297
  boost::optional<double> azimuth() const;
298
  
299
  // Construction assignment
300
  boost::optional<ConstructionBase> construction() const;
301
  bool setConstruction(const ConstructionBase& construction);
302
  
303
  // Space relationship
304
  boost::optional<Space> space() const;
305
  bool setSpace(Space& space);
306
  
307
  // Subsurfaces (windows, doors)
308
  std::vector<SubSurface> subSurfaces() const;
309
  
310
  // Adjacent surface
311
  boost::optional<Surface> adjacentSurface() const;
312
  bool setAdjacentSurface(Surface& surface);
313
};
314

315
/**
316
 * SubSurface - windows, doors, skylights
317
 */
318
class SubSurface : public ParentObject {
319
public:
320
  SubSurface(const std::vector<Point3d>& vertices, const Model& model);
321
  
322
  std::string subSurfaceType() const;
323
  bool setSubSurfaceType(const std::string& subSurfaceType);
324
  
325
  // Geometry
326
  std::vector<Point3d> vertices() const;
327
  bool setVertices(const std::vector<Point3d>& vertices);
328
  
329
  double grossArea() const;
330
  
331
  // Construction
332
  boost::optional<ConstructionBase> construction() const;
333
  bool setConstruction(const ConstructionBase& construction);
334
  
335
  // Surface relationship
336
  boost::optional<Surface> surface() const;
337
  bool setSurface(Surface& surface);
338
};
339

340
/**
341
 * Construction - layered construction assembly
342
 */
343
class Construction : public ConstructionBase {
344
public:
345
  Construction(const Model& model);
346
  
347
  // Layer management
348
  std::vector<Material> layers() const;
349
  bool insertLayer(unsigned layerIndex, const Material& material);
350
  bool eraseLayer(unsigned layerIndex);
351
  
352
  // Thermal properties
353
  boost::optional<double> thermalConductance() const;
354
  boost::optional<double> heatCapacity() const;
355
  
356
  // Reverse construction
357
  Construction reverseConstruction() const;
358
};
359
```
360

361
### HVAC System Objects
362

363
Core HVAC system components for air and plant loops.
364

365
```cpp { .api }
366
/**
367
 * AirLoopHVAC - main air handling system
368
 */
369
class AirLoopHVAC : public Loop {
370
public:
371
  AirLoopHVAC(const Model& model);
372
  
373
  // System components
374
  Node supplyInletNode() const;
375
  Node supplyOutletNode() const;
376
  Node demandInletNode() const;
377
  Node demandOutletNode() const;
378
  
379
  // Outdoor air system
380
  boost::optional<AirLoopHVACOutdoorAirSystem> airLoopHVACOutdoorAirSystem() const;
381
  bool setAirLoopHVACOutdoorAirSystem(const AirLoopHVACOutdoorAirSystem& outdoorAirSystem);
382
  
383
  // Thermal zones served
384
  std::vector<ThermalZone> thermalZones() const;
385
  bool addBranchForZone(ThermalZone& thermalZone);
386
  bool removeBranchForZone(ThermalZone& thermalZone);
387
  
388
  // Equipment on loop
389
  std::vector<ModelObject> supplyComponents() const;
390
  std::vector<ModelObject> demandComponents() const;
391
  
392
  // Sizing
393
  SizingSystem sizingSystem() const;
394
};
395

396
/**
397
 * PlantLoop - hydronic loop system
398
 */
399
class PlantLoop : public Loop {
400
public:
401
  PlantLoop(const Model& model);
402
  
403
  // Loop properties
404
  std::string fluidType() const;
405
  bool setFluidType(const std::string& fluidType);
406
  
407
  boost::optional<double> maximumLoopTemperature() const;
408
  bool setMaximumLoopTemperature(double maximumLoopTemperature);
409
  
410
  boost::optional<double> minimumLoopTemperature() const;
411
  bool setMinimumLoopTemperature(double minimumLoopTemperature);
412
  
413
  // Supply and demand sides
414
  std::vector<ModelObject> supplyComponents() const;
415
  std::vector<ModelObject> demandComponents() const;
416
  
417
  bool addSupplyBranchForComponent(HVACComponent& hvacComponent);
418
  bool addDemandBranchForComponent(HVACComponent& hvacComponent);
419
  
420
  // Sizing
421
  SizingPlant sizingPlant() const;
422
};
423

424
/**
425
 * Coil heating/cooling components
426
 */
427
class CoilHeatingWater : public WaterToAirComponent {
428
public:
429
  CoilHeatingWater(const Model& model, Schedule& availabilitySchedule);
430
  
431
  Schedule availabilitySchedule() const;
432
  bool setAvailabilitySchedule(Schedule& schedule);
433
  
434
  boost::optional<double> ratedCapacity() const;
435
  bool setRatedCapacity(double ratedCapacity);
436
  void autosizeRatedCapacity();
437
  
438
  boost::optional<double> ratedInletWaterTemperature() const;
439
  bool setRatedInletWaterTemperature(double ratedInletWaterTemperature);
440
};
441

442
class CoilCoolingWater : public WaterToAirComponent {
443
public:
444
  CoilCoolingWater(const Model& model, Schedule& availabilitySchedule);
445
  
446
  Schedule availabilitySchedule() const;
447
  bool setAvailabilitySchedule(Schedule& schedule);
448
  
449
  boost::optional<double> designWaterFlowRate() const;
450
  bool setDesignWaterFlowRate(double designWaterFlowRate);
451
  void autosizeDesignWaterFlowRate();
452
  
453
  boost::optional<double> designAirFlowRate() const;
454
  bool setDesignAirFlowRate(double designAirFlowRate);
455
  void autosizeDesignAirFlowRate();
456
};
457
```
458

459
### Schedule and Load Objects
460

461
Objects for defining time-varying inputs and internal loads.
462

463
```cpp { .api }
464
/**
465
 * Schedule objects for time-varying inputs
466
 */
467
class ScheduleConstant : public Schedule {
468
public:
469
  ScheduleConstant(const Model& model);
470
  
471
  double value() const;
472
  bool setValue(double value);
473
};
474

475
class ScheduleRuleset : public Schedule {
476
public:
477
  ScheduleRuleset(const Model& model);
478
  
479
  ScheduleDay defaultDaySchedule() const;
480
  ScheduleDay summerDesignDaySchedule() const;
481
  ScheduleDay winterDesignDaySchedule() const;
482
  
483
  std::vector<ScheduleRule> scheduleRules() const;
484
  
485
  ScheduleRule setWeekendRule(const ScheduleDay& scheduleDay);
486
  ScheduleRule setWeekdayRule(const ScheduleDay& scheduleDay);
487
};
488

489
/**
490
 * Internal load objects
491
 */
492
class People : public SpaceLoadInstance {
493
public:
494
  People(const PeopleDefinition& definition);
495
  
496
  PeopleDefinition peopleDefinition() const;
497
  bool setPeopleDefinition(const PeopleDefinition& definition);
498
  
499
  std::string numberofPeopleCalculationMethod() const;
500
  
501
  boost::optional<double> numberofPeople() const;
502
  bool setNumberofPeople(double numberofPeople);
503
  
504
  boost::optional<double> peopleperSpaceFloorArea() const;
505
  bool setPeopleperSpaceFloorArea(double peopleperSpaceFloorArea);
506
};
507

508
class Lights : public SpaceLoadInstance {
509
public:
510
  Lights(const LightsDefinition& definition);
511
  
512
  LightsDefinition lightsDefinition() const;
513
  bool setLightsDefinition(const LightsDefinition& definition);
514
  
515
  std::string designLevelCalculationMethod() const;
516
  
517
  boost::optional<double> lightingLevel() const;
518
  bool setLightingLevel(double lightingLevel);
519
  
520
  boost::optional<double> wattsperSpaceFloorArea() const;
521
  bool setWattsperSpaceFloorArea(double wattsperSpaceFloorArea);
522
};
523

524
class ElectricEquipment : public SpaceLoadInstance {
525
public:
526
  ElectricEquipment(const ElectricEquipmentDefinition& definition);
527
  
528
  ElectricEquipmentDefinition electricEquipmentDefinition() const;
529
  bool setElectricEquipmentDefinition(const ElectricEquipmentDefinition& definition);
530
  
531
  std::string designLevelCalculationMethod() const;
532
  
533
  boost::optional<double> designLevel() const;
534
  bool setDesignLevel(double designLevel);
535
  
536
  boost::optional<double> wattsperSpaceFloorArea() const;
537
  bool setWattsperSpaceFloorArea(double wattsperSpaceFloorArea);
538
};
539
```
540

541
## Common Usage Patterns
542

543
### Creating Building Geometry
544

545
```cpp
546
#include <openstudio/model/Model.hpp>
547
#include <openstudio/model/Space.hpp>
548
#include <openstudio/model/Surface.hpp>
549
#include <openstudio/utilities/geometry/Point3d.hpp>
550

551
Model model;
552

553
// Create a space
554
Space space(model);
555
space.setName("Office Space");
556

557
// Define vertices for a rectangular floor
558
std::vector<Point3d> vertices;
559
vertices.push_back(Point3d(0, 0, 0));
560
vertices.push_back(Point3d(10, 0, 0));
561
vertices.push_back(Point3d(10, 10, 0));
562
vertices.push_back(Point3d(0, 10, 0));
563

564
// Create floor surface
565
Surface floor(vertices, model);
566
floor.setSurfaceType("Floor");
567
floor.setSpace(space);
568

569
// Create walls with different heights
570
std::vector<Point3d> wallVertices;
571
wallVertices.push_back(Point3d(0, 0, 0));
572
wallVertices.push_back(Point3d(0, 0, 3));
573
wallVertices.push_back(Point3d(10, 0, 3));
574
wallVertices.push_back(Point3d(10, 0, 0));
575

576
Surface wall(wallVertices, model);
577
wall.setSurfaceType("Wall");
578
wall.setSpace(space);
579
```
580

581
### Setting up HVAC Systems
582

583
```cpp
584
#include <openstudio/model/Model.hpp>
585
#include <openstudio/model/AirLoopHVAC.hpp>
586
#include <openstudio/model/ThermalZone.hpp>
587

588
Model model;
589

590
// Create thermal zones
591
ThermalZone zone1(model);
592
ThermalZone zone2(model);
593

594
// Create air loop
595
AirLoopHVAC airLoop(model);
596
airLoop.setName("VAV System");
597

598
// Connect zones to air loop
599
airLoop.addBranchForZone(zone1);
600
airLoop.addBranchForZone(zone2);
601

602
// Add heating coil to supply side
603
Schedule alwaysOn = model.alwaysOnDiscreteSchedule();
604
CoilHeatingWater heatingCoil(model, alwaysOn);
605
airLoop.supplyComponents();
606
```
607

608
### Managing Object Collections
609

610
```cpp
611
// Get all zones in the model
612
std::vector<ThermalZone> allZones = model.getConcreteModelObjects<ThermalZone>();
613

614
// Filter zones by name pattern
615
std::vector<ThermalZone> officeZones;
616
for (const auto& zone : allZones) {
617
  if (zone.name() && zone.name()->find("Office") != std::string::npos) {
618
    officeZones.push_back(zone);
619
  }
620
}
621

622
// Get all surfaces in a space
623
if (!model.getConcreteModelObjects<Space>().empty()) {
624
  Space space = model.getConcreteModelObjects<Space>()[0];
625
  std::vector<Surface> surfaces = space.surfaces();
626
  
627
  // Count different surface types
628
  int walls = 0, floors = 0, ceilings = 0;
629
  for (const auto& surface : surfaces) {
630
    if (surface.surfaceType() == "Wall") walls++;
631
    else if (surface.surfaceType() == "Floor") floors++;
632
    else if (surface.surfaceType() == "RoofCeiling") ceilings++;
633
  }
634
}
635
```