0
# EnergyPlus Integration
1

2
Translation between OpenStudio models and EnergyPlus IDF format for building energy simulation. This module provides bidirectional conversion capabilities, enabling OpenStudio models to be simulated with EnergyPlus and EnergyPlus IDF files to be imported into OpenStudio.
3

4
## Capabilities
5

6
### Forward Translation
7

8
Converts OpenStudio Model objects to EnergyPlus IDF format for simulation.
9

10
```cpp { .api }
11
/**
12
 * Converts OpenStudio Model to EnergyPlus IDF format
13
 * Handles complete model translation with geometry, HVAC, and controls
14
 */
15
class ForwardTranslator {
16
public:
17
  // Constructor
18
  ForwardTranslator();
19
  
20
  // Main translation methods
21
  Workspace translateModel(const Model& model);
22
  boost::optional<IdfObject> translateModelObject(const ModelObject& modelObject);
23
  
24
  // Translation options
25
  bool excludeUnusedObjects() const;
26
  void setExcludeUnusedObjects(bool excludeUnusedObjects);
27
  
28
  bool excludeLCCObjects() const;
29
  void setExcludeLCCObjects(bool excludeLCCObjects);
30
  
31
  bool keepRunControlSpecialDays() const;
32
  void setKeepRunControlSpecialDays(bool keepRunControlSpecialDays);
33
  
34
  // Error and warning handling
35
  std::vector<LogMessage> errors() const;
36
  std::vector<LogMessage> warnings() const;
37
  std::vector<LogMessage> untranslatedIdfObjects() const;
38
  
39
  // Translation utilities
40
  boost::optional<EnergyPlusData> energyPlusData() const;
41
  void setEnergyPlusData(const EnergyPlusData& energyPlusData);
42
};
43
```
44

45
**Usage Examples:**
46

47
```cpp
48
#include <openstudio/model/Model.hpp>
49
#include <openstudio/energyplus/ForwardTranslator.hpp>
50
#include <openstudio/utilities/idf/Workspace.hpp>
51

52
using namespace openstudio;
53
using namespace openstudio::model;
54
using namespace openstudio::energyplus;
55

56
// Create and configure model
57
Model model;
58
Building building = model.getUniqueModelObject<Building>();
59
building.setName("Office Building");
60

61
// Create thermal zone with surfaces
62
ThermalZone zone(model);
63
Space space(model);
64
space.setThermalZone(zone);
65

66
// Set up forward translator
67
ForwardTranslator ft;
68
ft.setExcludeUnusedObjects(true);
69

70
// Translate to EnergyPlus
71
Workspace workspace = ft.translateModel(model);
72

73
// Check for translation issues
74
std::vector<LogMessage> errors = ft.errors();
75
std::vector<LogMessage> warnings = ft.warnings();
76

77
if (!errors.empty()) {
78
  for (const auto& error : errors) {
79
    std::cout << "Error: " << error.logMessage() << std::endl;
80
  }
81
} else {
82
  // Save IDF file
83
  workspace.save(Path("building.idf"), true);
84
}
85
```
86

87
### Reverse Translation
88

89
Converts EnergyPlus IDF files back to OpenStudio Model format.
90

91
```cpp { .api }
92
/**
93
 * Converts EnergyPlus IDF to OpenStudio Model format
94
 * Reconstructs object relationships and hierarchy from flat IDF structure
95
 */
96
class ReverseTranslator {
97
public:
98
  // Constructor
99
  ReverseTranslator();
100
  
101
  // Main translation methods
102
  boost::optional<Model> translateWorkspace(const Workspace& workspace);
103
  boost::optional<ModelObject> translateWorkspaceObject(const WorkspaceObject& workspaceObject,
104
                                                        Model& model);
105
  
106
  // Translation options
107
  bool keepRunControlSpecialDays() const;
108
  void setKeepRunControlSpecialDays(bool keepRunControlSpecialDays);
109
  
110
  // Error and warning handling
111
  std::vector<LogMessage> errors() const;
112
  std::vector<LogMessage> warnings() const;
113
  std::vector<LogMessage> untranslatedIdfObjects() const;
114
  
115
  // Progress tracking
116
  void setProgressBar(ProgressBar* progressBar);
117
};
118
```
119

120
**Usage Examples:**
121

122
```cpp
123
#include <openstudio/utilities/idf/Workspace.hpp>
124
#include <openstudio/energyplus/ReverseTranslator.hpp>
125

126
using namespace openstudio;
127
using namespace openstudio::energyplus;
128

129
// Load EnergyPlus IDF file
130
boost::optional<Workspace> workspace = Workspace::load(Path("existing_building.idf"));
131

132
if (workspace) {
133
  // Set up reverse translator  
134
  ReverseTranslator rt;
135
  
136
  // Translate to OpenStudio model
137
  boost::optional<Model> model = rt.translateWorkspace(*workspace);
138
  
139
  if (model) {
140
    // Check translation results
141
    std::vector<LogMessage> warnings = rt.warnings();
142
    for (const auto& warning : warnings) {
143
      std::cout << "Warning: " << warning.logMessage() << std::endl;
144
    }
145
    
146
    // Save as OpenStudio model
147
    model->save(Path("converted_building.osm"), true);
148
    
149
    // Access translated objects
150
    std::vector<ThermalZone> zones = model->getConcreteModelObjects<ThermalZone>();
151
    std::cout << "Translated " << zones.size() << " thermal zones" << std::endl;
152
  }
153
}
154
```
155

156
### Geometry Translation
157

158
Specialized handling for geometric data conversion between coordinate systems.
159

160
```cpp { .api }
161
/**
162
 * Handles geometric data translation and coordinate system conversions
163
 */
164
class GeometryTranslator {
165
public:
166
  // Surface coordinate conversion
167
  static std::vector<Point3d> convertVertices(const std::vector<Point3d>& vertices);
168
  
169
  // Zone geometry processing
170
  static boost::optional<double> calculateZoneVolume(const std::vector<Surface>& surfaces);
171
  static boost::optional<double> calculateZoneFloorArea(const std::vector<Surface>& surfaces);
172
  
173
  // Shading calculations
174
  static std::vector<ShadingSurface> calculateBuildingShading(const Model& model);
175
  
176
  // Geometry validation
177
  static bool validateSurfaceGeometry(const Surface& surface);
178
  static bool validateZoneGeometry(const ThermalZone& zone);
179
  
180
  // Coordinate system transformations
181
  static Transformation buildingTransformation(const Building& building);
182
  static std::vector<Point3d> applyBuildingTransformation(const std::vector<Point3d>& vertices,
183
                                                          const Building& building);
184
};
185
```
186

187
### Translation Utilities
188

189
Helper functions and data structures for translation operations.
190

191
```cpp { .api }
192
/**
193
 * Translation mapping and utilities
194
 */
195
namespace TranslationUtils {
196
  
197
  // Object type mappings
198
  std::string mapModelObjectType(IddObjectType modelObjectType);
199
  boost::optional<IddObjectType> mapIdfObjectType(IddObjectType idfObjectType);
200
  
201
  // Field mapping utilities
202
  boost::optional<unsigned> mapModelField(IddObjectType modelType, 
203
                                          unsigned modelFieldIndex,
204
                                          IddObjectType idfType);
205
  
206
  // Schedule translation helpers
207
  boost::optional<IdfObject> translateSchedule(const Schedule& schedule);
208
  boost::optional<Schedule> reverseTranslateSchedule(const WorkspaceObject& idfObject,
209
                                                     Model& model);
210
  
211
  // Construction translation helpers
212
  boost::optional<IdfObject> translateConstruction(const ConstructionBase& construction);
213
  boost::optional<ConstructionBase> reverseTranslateConstruction(const WorkspaceObject& idfObject,
214
                                                                 Model& model);
215
  
216
  // Material translation helpers
217
  std::vector<IdfObject> translateMaterials(const Construction& construction);
218
  std::vector<Material> reverseTranslateMaterials(const std::vector<WorkspaceObject>& idfObjects,
219
                                                  Model& model);
220
}
221

222
/**
223
 * EnergyPlus version and data management
224
 */
225
class EnergyPlusData {
226
public:
227
  // Version information
228
  std::string version() const;
229
  void setVersion(const std::string& version);
230
  
231
  // IDD access
232
  IddFile iddFile() const;
233
  void setIddFile(const IddFile& iddFile);
234
  
235
  // Default objects
236
  std::vector<IdfObject> defaultObjects() const;
237
  void addDefaultObject(const IdfObject& object);
238
  
239
  // Translation mappings
240
  std::map<std::string, std::string> objectTypeMap() const;
241
  void addObjectTypeMapping(const std::string& osType, const std::string& epType);
242
};
243
```
244

245
### HVAC Translation
246

247
Specialized translation for HVAC systems and components.
248

249
```cpp { .api }
250
/**
251
 * HVAC system translation utilities
252
 */
253
namespace HVACTranslation {
254
  
255
  // Air loop translation
256
  std::vector<IdfObject> translateAirLoopHVAC(const AirLoopHVAC& airLoop);
257
  boost::optional<AirLoopHVAC> reverseTranslateAirLoopHVAC(const std::vector<WorkspaceObject>& idfObjects,
258
                                                           Model& model);
259
  
260
  // Plant loop translation
261
  std::vector<IdfObject> translatePlantLoop(const PlantLoop& plantLoop);
262
  boost::optional<PlantLoop> reverseTranslatePlantLoop(const std::vector<WorkspaceObject>& idfObjects,
263
                                                       Model& model);
264
  
265
  // Zone equipment translation
266
  std::vector<IdfObject> translateZoneHVACEquipment(const ModelObject& zoneEquipment);
267
  std::vector<ModelObject> reverseTranslateZoneHVACEquipment(const std::vector<WorkspaceObject>& idfObjects,
268
                                                            Model& model);
269
  
270
  // Component connection utilities
271
  bool connectComponents(ModelObject& sourceComponent,
272
                        unsigned sourcePort,
273
                        ModelObject& targetComponent,
274
                        unsigned targetPort);
275
  
276
  // Node management
277
  std::vector<Node> createSystemNodes(const Model& model, unsigned count);
278
  void cleanupUnusedNodes(Model& model);
279
}
280
```
281

282
### Simulation Control Translation
283

284
Translation of simulation settings and run parameters.
285

286
```cpp { .api }
287
/**
288
 * Simulation control and run parameter translation
289
 */
290
namespace SimulationTranslation {
291
  
292
  // Simulation control objects
293
  IdfObject translateSimulationControl(const SimulationControl& simControl);
294
  boost::optional<SimulationControl> reverseTranslateSimulationControl(const WorkspaceObject& idfObject,
295
                                                                        Model& model);
296
  
297
  // Run period translation
298
  std::vector<IdfObject> translateRunPeriods(const Model& model);
299
  std::vector<RunPeriod> reverseTranslateRunPeriods(const std::vector<WorkspaceObject>& idfObjects,
300
                                                    Model& model);
301
  
302
  // Sizing parameters
303
  std::vector<IdfObject> translateSizingParameters(const Model& model);
304
  void reverseTranslateSizingParameters(const std::vector<WorkspaceObject>& idfObjects,
305
                                       Model& model);
306
  
307
  // Output requests
308
  std::vector<IdfObject> translateOutputRequests(const Model& model);
309
  void addOutputRequests(Model& model, const std::vector<WorkspaceObject>& idfObjects);
310
  
311
  // Weather file handling
312
  boost::optional<IdfObject> translateWeatherFile(const WeatherFile& weatherFile);
313
  boost::optional<WeatherFile> reverseTranslateWeatherFile(const WorkspaceObject& idfObject,
314
                                                          Model& model);
315
}
316
```
317

318
## Common Usage Patterns
319

320
### Complete Model Translation Workflow
321

322
```cpp
323
#include <openstudio/model/Model.hpp>
324
#include <openstudio/energyplus/ForwardTranslator.hpp>
325
#include <openstudio/utilities/idf/Workspace.hpp>
326

327
using namespace openstudio;
328
using namespace openstudio::model;
329
using namespace openstudio::energyplus;
330

331
// Load OpenStudio model
332
boost::optional<Model> model = Model::load(Path("building.osm"));
333

334
if (model) {
335
  // Configure forward translator
336
  ForwardTranslator ft;
337
  ft.setExcludeUnusedObjects(true);
338
  ft.setExcludeLCCObjects(false);
339
  
340
  // Translate model
341
  Workspace workspace = ft.translateModel(*model);
342
  
343
  // Handle translation messages
344
  std::vector<LogMessage> errors = ft.errors();
345
  std::vector<LogMessage> warnings = ft.warnings();
346
  
347
  std::cout << "Translation completed with " << warnings.size() 
348
            << " warnings and " << errors.size() << " errors" << std::endl;
349
  
350
  if (errors.empty()) {
351
    // Save IDF for simulation
352
    bool success = workspace.save(Path("building.idf"), true);
353
    if (success) {
354
      std::cout << "IDF file saved successfully" << std::endl;
355
    }
356
  } else {
357
    // Log errors for debugging
358
    for (const auto& error : errors) {
359
      std::cout << "Translation Error: " << error.logMessage() << std::endl;
360
    }
361
  }
362
}
363
```
364

365
### IDF Import and Modification
366

367
```cpp
368
#include <openstudio/utilities/idf/Workspace.hpp>
369
#include <openstudio/energyplus/ReverseTranslator.hpp>
370
#include <openstudio/energyplus/ForwardTranslator.hpp>
371

372
using namespace openstudio;
373
using namespace openstudio::energyplus;
374

375
// Import existing IDF file
376
boost::optional<Workspace> workspace = Workspace::load(Path("reference_building.idf"));
377

378
if (workspace) {
379
  // Convert to OpenStudio model
380
  ReverseTranslator rt;
381
  boost::optional<Model> model = rt.translateWorkspace(*workspace);
382
  
383
  if (model) {
384
    // Modify the model
385
    Building building = model->getUniqueModelObject<Building>();
386
    building.setName("Modified Building");
387
    
388
    // Change all zone setpoints
389
    std::vector<ThermalZone> zones = model->getConcreteModelObjects<ThermalZone>();
390
    for (auto& zone : zones) {
391
      boost::optional<ThermostatSetpointDualSetpoint> thermostat = 
392
        zone.thermostatSetpointDualSetpoint();
393
      
394
      if (thermostat) {
395
        // Modify setpoint schedules if needed
396
      }
397
    }
398
    
399
    // Translate back to IDF
400
    ForwardTranslator ft;
401
    Workspace modifiedWorkspace = ft.translateModel(*model);
402
    modifiedWorkspace.save(Path("modified_building.idf"), true);
403
  }
404
}
405
```
406

407
### Translation Error Handling
408

409
```cpp
410
#include <openstudio/energyplus/ForwardTranslator.hpp>
411

412
using namespace openstudio;
413
using namespace openstudio::energyplus;
414

415
Model model;
416
// ... build model ...
417

418
ForwardTranslator ft;
419
Workspace workspace = ft.translateModel(model);
420

421
// Comprehensive error checking
422
std::vector<LogMessage> errors = ft.errors();
423
std::vector<LogMessage> warnings = ft.warnings();
424
std::vector<LogMessage> untranslated = ft.untranslatedIdfObjects();
425

426
// Log all issues
427
if (!errors.empty()) {
428
  std::cout << "\nTranslation Errors:" << std::endl;
429
  for (const auto& error : errors) {
430
    std::cout << "  " << error.logMessage() << std::endl;
431
  }
432
}
433

434
if (!warnings.empty()) {
435
  std::cout << "\nTranslation Warnings:" << std::endl;
436
  for (const auto& warning : warnings) {
437
    std::cout << "  " << warning.logMessage() << std::endl;
438
  }
439
}
440

441
if (!untranslated.empty()) {
442
  std::cout << "\nUntranslated Objects:" << std::endl;
443
  for (const auto& untrans : untranslated) {
444
    std::cout << "  " << untrans.logMessage() << std::endl;
445
  }
446
}
447

448
// Only proceed if no critical errors
449
if (errors.empty()) {
450
  workspace.save(Path("building.idf"), true);
451
  std::cout << "\nTranslation completed successfully!" << std::endl;
452
}
453
```
454

455
### HVAC System Translation
456

457
```cpp
458
#include <openstudio/model/AirLoopHVAC.hpp>
459
#include <openstudio/model/PlantLoop.hpp>
460
#include <openstudio/energyplus/ForwardTranslator.hpp>
461

462
using namespace openstudio;
463
using namespace openstudio::model;
464
using namespace openstudio::energyplus;
465

466
Model model;
467

468
// Create air loop system
469
AirLoopHVAC airLoop(model);
470
airLoop.setName("VAV System 1");
471

472
// Add zones to air loop
473
ThermalZone zone1(model);
474
ThermalZone zone2(model);
475
airLoop.addBranchForZone(zone1);
476
airLoop.addBranchForZone(zone2);
477

478
// Create hot water plant loop
479
PlantLoop hotWaterLoop(model);
480
hotWaterLoop.setName("Hot Water Loop");
481

482
// Add boiler to plant loop
483
Schedule alwaysOn = model.alwaysOnDiscreteSchedule();
484
BoilerHotWater boiler(model);
485
hotWaterLoop.addSupplyBranchForComponent(boiler);
486

487
// Add heating coil to air loop and connect to plant
488
CoilHeatingWater heatingCoil(model, alwaysOn);
489
// Note: Connection would be done through the model's connect method
490
model.connect(hotWaterLoop.supplyOutletNode(), heatingCoil.waterInletModelObject().get(),
491
              heatingCoil.waterOutletModelObject().get(), hotWaterLoop.demandInletNode());
492

493
// Translate complete system
494
ForwardTranslator ft;
495
Workspace workspace = ft.translateModel(model);
496

497
// Check HVAC translation specifically
498
std::vector<LogMessage> warnings = ft.warnings();
499
for (const auto& warning : warnings) {
500
  if (warning.logMessage().find("HVAC") != std::string::npos || 
501
      warning.logMessage().find("AirLoop") != std::string::npos) {
502
    std::cout << "HVAC Warning: " << warning.logMessage() << std::endl;
503
  }
504
}
505
```