0
# Utility Classes
1

2
Comprehensive utility classes for geometry, units, file I/O, and data structures that form the foundation of the OpenStudio SDK. These utilities provide cross-platform infrastructure for handling physical units, 3D geometry, file operations, and data management.
3

4
## Capabilities
5

6
### File System Operations
7

8
Cross-platform file and path handling with comprehensive path manipulation capabilities.
9

10
```cpp { .api }
11
/**
12
 * Cross-platform path handling and file system operations
13
 */
14
class Path {
15
public:
16
  // Constructors
17
  Path();
18
  Path(const std::string& p);
19
  Path(const char* p);
20
  
21
  // Path conversion
22
  std::string string() const;
23
  std::wstring wstring() const;
24
  std::string generic_string() const;
25
  
26
  // Path components
27
  std::string filename() const;
28
  std::string stem() const;
29
  std::string extension() const;
30
  Path parent_path() const;
31
  Path root_path() const;
32
  
33
  // Path operations
34
  Path operator/(const Path& p) const;
35
  Path& operator/=(const Path& p);
36
  
37
  // File system queries
38
  bool exists() const;
39
  bool is_complete() const;
40
  bool is_directory() const;
41
  bool is_regular_file() const;
42
  bool empty() const;
43
  
44
  // Path manipulation
45
  Path replace_extension(const std::string& new_extension = std::string()) const;
46
  Path make_preferred() const;
47
};
48

49
namespace filesystem {
50
  // File system operations
51
  bool exists(const Path& p);
52
  bool is_directory(const Path& p);
53
  bool is_regular_file(const Path& p);
54
  bool create_directories(const Path& p);
55
  bool remove(const Path& p);
56
  bool copy_file(const Path& from, const Path& to);
57
  
58
  uintmax_t file_size(const Path& p);
59
  std::time_t last_write_time(const Path& p);
60
  
61
  // Directory iteration
62
  std::vector<Path> directory_iterator(const Path& p);
63
  std::vector<Path> recursive_directory_iterator(const Path& p);
64
}
65
```
66

67
**Usage Examples:**
68

69
```cpp
70
#include <openstudio/utilities/core/Path.hpp>
71

72
using namespace openstudio;
73

74
// Path construction and manipulation
75
Path modelDir("/home/user/models");
76
Path modelFile = modelDir / "building.osm";
77

78
// Path queries
79
if (modelFile.exists() && modelFile.is_regular_file()) {
80
  std::string filename = modelFile.filename(); // "building.osm"
81
  std::string stem = modelFile.stem();         // "building"
82
  std::string ext = modelFile.extension();    // ".osm"
83
}
84

85
// Create output path with different extension
86
Path idfFile = modelFile.replace_extension(".idf");
87

88
// File operations
89
if (!filesystem::exists(modelDir)) {
90
  filesystem::create_directories(modelDir);
91
}
92
```
93

94
### 3D Geometry Operations
95

96
Comprehensive 3D geometric operations for building modeling and analysis.
97

98
```cpp { .api }
99
/**
100
 * 3D point representation
101
 */
102
class Point3d {
103
public:
104
  // Constructors
105
  Point3d();
106
  Point3d(double x, double y, double z);
107
  
108
  // Coordinate access
109
  double x() const;
110
  double y() const;
111
  double z() const;
112
  void setX(double x);
113
  void setY(double y);
114
  void setZ(double z);
115
  
116
  // Vector operations
117
  Vector3d operator-(const Point3d& other) const;
118
  Point3d operator+(const Vector3d& vec) const;
119
  Point3d operator-(const Vector3d& vec) const;
120
  
121
  // Distance calculations
122
  double distanceTo(const Point3d& other) const;
123
};
124

125
/**
126
 * 3D vector representation
127
 */
128
class Vector3d {
129
public:
130
  // Constructors
131
  Vector3d();
132
  Vector3d(double x, double y, double z);
133
  
134
  // Component access
135
  double x() const;
136
  double y() const;
137
  double z() const;
138
  void setX(double x);
139
  void setY(double y);
140
  void setZ(double z);
141
  
142
  // Vector operations
143
  double length() const;
144
  double lengthSquared() const;
145
  bool normalize();
146
  Vector3d normalized() const;
147
  
148
  Vector3d operator+(const Vector3d& other) const;
149
  Vector3d operator-(const Vector3d& other) const;
150
  Vector3d operator*(double scalar) const;
151
  Vector3d operator/(double scalar) const;
152
  
153
  // Vector products
154
  double dot(const Vector3d& other) const;
155
  Vector3d cross(const Vector3d& other) const;
156
};
157

158
/**
159
 * 3D transformation matrix
160
 */
161
class Transformation {
162
public:
163
  // Constructors
164
  Transformation();
165
  Transformation(const Vector3d& translation);
166
  Transformation(const Vector3d& rotationAxis, double rotationAngle);
167
  
168
  // Static factory methods
169
  static Transformation translation(const Vector3d& translation);
170
  static Transformation rotation(const Vector3d& axis, double angle);
171
  static Transformation rotation(const Point3d& origin, const Vector3d& axis, double angle);
172
  
173
  // Matrix operations
174
  Transformation operator*(const Transformation& other) const;
175
  Transformation inverse() const;
176
  
177
  // Transform points and vectors
178
  Point3d operator*(const Point3d& point) const;
179
  Vector3d operator*(const Vector3d& vector) const;
180
  std::vector<Point3d> operator*(const std::vector<Point3d>& points) const;
181
  
182
  // Matrix access
183
  boost::optional<Vector3d> translation() const;
184
  boost::optional<Vector3d> rotationAxis() const;
185
  boost::optional<double> rotationAngle() const;
186
};
187

188
/**
189
 * 3D polygon operations
190
 */
191
class Polygon3d {
192
public:
193
  // Constructors
194
  Polygon3d(const std::vector<Point3d>& vertices);
195
  
196
  // Vertex access
197
  std::vector<Point3d> vertices() const;
198
  unsigned numVertices() const;
199
  
200
  // Geometric properties
201
  boost::optional<Vector3d> outwardNormal() const;
202
  boost::optional<double> area() const;
203
  boost::optional<Point3d> centroid() const;
204
  boost::optional<Plane> plane() const;
205
  
206
  // Geometric operations
207
  bool isPlanar() const;
208
  bool isConvex() const;
209
  std::vector<Polygon3d> triangulate() const;
210
  
211
  // Point-in-polygon tests
212
  bool pointInside(const Point3d& point) const;
213
};
214

215
/**
216
 * Bounding box operations
217
 */
218
class BoundingBox {
219
public:
220
  // Constructors
221
  BoundingBox();
222
  BoundingBox(const Point3d& minCorner, const Point3d& maxCorner);
223
  
224
  // Corner access
225
  Point3d minCorner() const;
226
  Point3d maxCorner() const;
227
  
228
  // Dimension queries
229
  double minX() const;
230
  double maxX() const;
231
  double minY() const;
232
  double maxY() const;
233
  double minZ() const;
234
  double maxZ() const;
235
  
236
  // Volume and area
237
  double volume() const;
238
  double surfaceArea() const;
239
  
240
  // Operations
241
  void addPoint(const Point3d& point);
242
  void addPoints(const std::vector<Point3d>& points);
243
  bool intersects(const BoundingBox& other) const;
244
  bool contains(const Point3d& point) const;
245
};
246
```
247

248
### Physical Units and Quantities
249

250
Comprehensive unit system with automatic conversions and quantity management.
251

252
```cpp { .api }
253
/**
254
 * Physical unit representation with conversion capabilities
255
 */
256
class Unit {
257
public:
258
  // Constructors
259
  Unit();
260
  Unit(UnitSystem system = UnitSystem::Mixed);
261
  
262
  // Unit system queries
263
  UnitSystem system() const;
264
  
265
  // Base unit operations
266
  void setBaseUnitExponent(const std::string& baseUnit, int exponent);
267
  int baseUnitExponent(const std::string& baseUnit) const;
268
  
269
  // Unit operations
270
  Unit operator*(const Unit& rUnit) const;
271
  Unit operator/(const Unit& rUnit) const;
272
  Unit pow(int expNum, int expDen = 1) const;
273
  
274
  // String representation
275
  std::string standardString() const;
276
  std::string prettyString() const;
277
};
278

279
/**
280
 * Quantity - value with associated units
281
 */
282
class Quantity {
283
public:
284
  // Constructors
285
  Quantity();
286
  Quantity(double value);
287
  Quantity(double value, const Unit& units);
288
  
289
  // Value and unit access
290
  double value() const;
291
  Unit units() const;
292
  UnitSystem system() const;
293
  
294
  // Value modification
295
  void setValue(double value);
296
  bool setUnits(const Unit& units);
297
  
298
  // Unit conversion
299
  boost::optional<Quantity> convert(const Unit& targetUnits) const;
300
  boost::optional<Quantity> convert(UnitSystem targetSystem) const;
301
  
302
  // Arithmetic operations
303
  Quantity operator+(const Quantity& rQuantity) const;
304
  Quantity operator-(const Quantity& rQuantity) const;
305
  Quantity operator*(const Quantity& rQuantity) const;
306
  Quantity operator/(const Quantity& rQuantity) const;
307
  Quantity pow(int expNum, int expDen = 1) const;
308
};
309

310
/**
311
 * Collection of quantities with consistent units
312
 */
313
class OSQuantityVector {
314
public:
315
  // Constructors
316
  OSQuantityVector();
317
  OSQuantityVector(const Unit& units);
318
  OSQuantityVector(const std::vector<Quantity>& values);
319
  
320
  // Vector operations
321
  unsigned size() const;
322
  bool empty() const;
323
  void push_back(const Quantity& q);
324
  void clear();
325
  
326
  // Unit operations
327
  Unit units() const;
328
  bool setUnits(const Unit& units);
329
  boost::optional<OSQuantityVector> convert(const Unit& targetUnits) const;
330
  
331
  // Value access
332
  std::vector<double> values() const;
333
  std::vector<Quantity> quantities() const;
334
  Quantity getQuantity(unsigned index) const;
335
};
336

337
// Common unit factory functions
338
namespace createUnits {
339
  // Length units
340
  Unit createSILength();     // m
341
  Unit createIPLength();     // ft
342
  Unit createFeet();
343
  Unit createInches();
344
  Unit createMeters();
345
  Unit createCentimeters();
346
  
347
  // Area units
348
  Unit createSIArea();       // m^2
349
  Unit createIPArea();       // ft^2
350
  
351
  // Volume units
352
  Unit createSIVolume();     // m^3
353
  Unit createIPVolume();     // ft^3
354
  
355
  // Temperature units
356
  Unit createSITemperature(); // K
357
  Unit createIPTemperature(); // R
358
  Unit createCelsiusTemperature(); // C
359
  Unit createFahrenheitTemperature(); // F
360
  
361
  // Energy units
362
  Unit createSIEnergy();     // J
363
  Unit createIPEnergy();     // Btu
364
  Unit createKWh();
365
  
366
  // Power units
367
  Unit createSIPower();      // W
368
  Unit createIPPower();      // Btu/h
369
}
370
```
371

372
### Time and Date Handling
373

374
Comprehensive time management for simulation and scheduling operations.
375

376
```cpp { .api }
377
/**
378
 * Time duration representation
379
 */
380
class Time {
381
public:
382
  // Constructors
383
  Time();
384
  Time(double totalDays);
385
  Time(int days, int hours = 0, int minutes = 0, int seconds = 0);
386
  
387
  // Component access
388
  int days() const;
389
  int hours() const;
390
  int minutes() const;
391
  int seconds() const;
392
  
393
  // Total time access
394
  double totalDays() const;
395
  double totalHours() const;
396
  double totalMinutes() const;
397
  double totalSeconds() const;
398
  
399
  // Arithmetic operations
400
  Time operator+(const Time& time) const;
401
  Time operator-(const Time& time) const;
402
  Time operator*(double mult) const;
403
  Time operator/(double div) const;
404
  
405
  // String representation
406
  std::string toString() const;
407
};
408

409
/**
410
 * Calendar date representation
411
 */
412
class Date {
413
public:
414
  // Constructors
415
  Date();
416
  Date(MonthOfYear monthOfYear, unsigned dayOfMonth);
417
  Date(MonthOfYear monthOfYear, unsigned dayOfMonth, int year);
418
  Date(unsigned dayOfYear, int year);
419
  
420
  // Component access
421
  int year() const;
422
  MonthOfYear monthOfYear() const;
423
  unsigned dayOfMonth() const;
424
  unsigned dayOfYear() const;
425
  DayOfWeek dayOfWeek() const;
426
  
427
  // Date operations
428
  Date operator+(const Time& time) const;
429
  Date operator-(const Time& time) const;
430
  Time operator-(const Date& date) const;
431
  
432
  // Leap year handling
433
  bool isLeapYear() const;
434
  static bool isLeapYear(int year);
435
  
436
  // String representation
437
  std::string toString() const;
438
};
439

440
/**
441
 * Combined date and time
442
 */
443
class DateTime {
444
public:
445
  // Constructors
446
  DateTime();
447
  DateTime(const Date& date);
448
  DateTime(const Date& date, const Time& time);
449
  
450
  // Component access
451
  Date date() const;
452
  Time time() const;
453
  
454
  // Arithmetic operations
455
  DateTime operator+(const Time& time) const;
456
  DateTime operator-(const Time& time) const;
457
  Time operator-(const DateTime& dateTime) const;
458
  
459
  // String representation
460
  std::string toString() const;
461
};
462

463
// Enumeration types
464
enum class MonthOfYear {
465
  Jan = 1, Feb, Mar, Apr, May, Jun,
466
  Jul, Aug, Sep, Oct, Nov, Dec
467
};
468

469
enum class DayOfWeek {
470
  Sunday = 0, Monday, Tuesday, Wednesday, 
471
  Thursday, Friday, Saturday
472
};
473
```
474

475
### Logging Framework
476

477
Comprehensive logging system with multiple output targets and severity levels.
478

479
```cpp { .api }
480
/**
481
 * Logging framework with multiple severity levels
482
 */
483
class Logger {
484
public:
485
  // Static access to loggers
486
  static Logger& instance();
487
  static LoggerType& standardOut();
488
  
489
  // Logging methods
490
  void logMessage(LogLevel level, const LogChannel& channel, const std::string& message);
491
  
492
  // Log level control
493
  void setLogLevel(LogLevel level);
494
  LogLevel logLevel() const;
495
  
496
  // Log sinks
497
  void addLogSink(boost::shared_ptr<LogSink> logSink);
498
  void removeLogSink(boost::shared_ptr<LogSink> logSink);
499
};
500

501
/**
502
 * Base class for log output destinations
503
 */
504
class LogSink {
505
public:
506
  virtual ~LogSink() = default;
507
  
508
  // Core logging method
509
  virtual void logMessage(const LogMessage& logMessage) = 0;
510
  
511
  // Level filtering
512
  void setLogLevel(LogLevel logLevel);
513
  LogLevel logLevel() const;
514
  
515
  // Channel filtering
516
  void setChannelRegex(const std::string& channelRegex);
517
  std::string channelRegex() const;
518
  
519
  // Threading
520
  void setThreadId(boost::thread::id threadId);
521
  boost::thread::id threadId() const;
522
};
523

524
/**
525
 * File-based log output
526
 */
527
class FileLogSink : public LogSink {
528
public:
529
  FileLogSink(const Path& path);
530
  
531
  Path path() const;
532
  
533
  virtual void logMessage(const LogMessage& logMessage) override;
534
};
535

536
/**
537
 * String stream log output for testing
538
 */
539
class StringStreamLogSink : public LogSink {
540
public:
541
  StringStreamLogSink();
542
  
543
  std::string logMessages() const;
544
  std::vector<LogMessage> logMessagesVec() const;
545
  
546
  virtual void logMessage(const LogMessage& logMessage) override;
547
};
548

549
// Log level enumeration
550
enum class LogLevel {
551
  Trace = -3,
552
  Debug = -2, 
553
  Info = -1,
554
  Warn = 0,
555
  Error = 1,
556
  Fatal = 2
557
};
558

559
// Logging macros
560
#define LOG(level, channel) \
561
  if (openstudio::Logger::instance().logLevel() <= level) \
562
    openstudio::Logger::instance().logMessage(level, channel, "")
563

564
#define LOG_FREE(level, channel, message) \
565
  openstudio::Logger::instance().logMessage(level, channel, message)
566
```
567

568
### Data Structures
569

570
Mathematical data structures for numerical analysis and data management.
571

572
```cpp { .api }
573
/**
574
 * Mathematical matrix operations
575
 */
576
class Matrix {
577
public:
578
  // Constructors
579
  Matrix();
580
  Matrix(unsigned m, unsigned n, double value = 0.0);
581
  Matrix(const std::vector<std::vector<double>>& vector);
582
  
583
  // Dimension access
584
  unsigned size1() const; // rows
585
  unsigned size2() const; // columns
586
  
587
  // Element access
588
  double operator()(unsigned i, unsigned j) const;
589
  double& operator()(unsigned i, unsigned j);
590
  
591
  // Matrix operations
592
  Matrix operator+(const Matrix& other) const;
593
  Matrix operator-(const Matrix& other) const;
594
  Matrix operator*(const Matrix& other) const;
595
  Matrix operator*(double scalar) const;
596
  
597
  // Matrix properties
598
  Matrix transpose() const;
599
  boost::optional<Matrix> inverse() const;
600
  double determinant() const;
601
  
602
  // Row and column operations
603
  Vector getRow(unsigned i) const;
604
  Vector getColumn(unsigned j) const;
605
  void setRow(unsigned i, const Vector& row);
606
  void setColumn(unsigned j, const Vector& column);
607
};
608

609
/**
610
 * Mathematical vector operations
611
 */
612
class Vector {
613
public:
614
  // Constructors
615
  Vector();
616
  Vector(unsigned size, double value = 0.0);
617
  Vector(const std::vector<double>& vector);
618
  
619
  // Size operations
620
  unsigned size() const;
621
  void resize(unsigned size);
622
  
623
  // Element access
624
  double operator()(unsigned i) const;
625
  double& operator()(unsigned i);
626
  double operator[](unsigned i) const;
627
  double& operator[](unsigned i);
628
  
629
  // Vector operations
630
  Vector operator+(const Vector& other) const;
631
  Vector operator-(const Vector& other) const;
632
  Vector operator*(double scalar) const;
633
  double dot(const Vector& other) const;
634
  
635
  // Vector properties
636
  double length() const;
637
  double sum() const;
638
  double mean() const;
639
  double minimum() const;
640
  double maximum() const;
641
};
642

643
/**
644
 * Time series data management
645
 */
646
class TimeSeries {
647
public:
648
  // Constructors
649
  TimeSeries();
650
  TimeSeries(const Date& startDate, 
651
             const Time& intervalLength,
652
             const Vector& values,
653
             const std::string& units);
654
  
655
  // Data access
656
  Date startDate() const;
657
  Time intervalLength() const;
658
  std::vector<DateTime> dateTimes() const;
659
  Vector values() const;
660
  std::string units() const;
661
  
662
  // Value access by time
663
  double value(const DateTime& dateTime) const;
664
  std::vector<double> values(const DateTime& startDateTime, 
665
                            const DateTime& endDateTime) const;
666
  
667
  // Statistical operations
668
  double minimum() const;
669
  double maximum() const;
670
  double mean() const;
671
  double sum() const;
672
  
673
  // Time series operations
674
  TimeSeries operator+(const TimeSeries& other) const;
675
  TimeSeries operator-(const TimeSeries& other) const;
676
  TimeSeries operator*(double scalar) const;
677
};
678
```
679

680
## Common Usage Patterns
681

682
### File and Path Operations
683

684
```cpp
685
#include <openstudio/utilities/core/Path.hpp>
686

687
using namespace openstudio;
688

689
// Working with model files
690
Path modelDir = Path("/home/user/models");
691
Path osmFile = modelDir / "office_building.osm";
692
Path idfFile = osmFile.replace_extension(".idf");
693

694
// Check file existence and create directories
695
if (!filesystem::exists(modelDir)) {
696
  filesystem::create_directories(modelDir);
697
}
698

699
// File operations with error handling
700
if (filesystem::exists(osmFile)) {
701
  // Backup existing file
702
  Path backupFile = osmFile.replace_extension(".osm.bak");
703
  filesystem::copy_file(osmFile, backupFile);
704
  
705
  std::cout << "File size: " << filesystem::file_size(osmFile) << " bytes" << std::endl;
706
}
707
```
708

709
### Geometric Calculations
710

711
```cpp
712
#include <openstudio/utilities/geometry/Point3d.hpp>
713
#include <openstudio/utilities/geometry/Vector3d.hpp>
714
#include <openstudio/utilities/geometry/Transformation.hpp>
715

716
using namespace openstudio;
717

718
// Create building geometry
719
std::vector<Point3d> floorVertices;
720
floorVertices.push_back(Point3d(0, 0, 0));
721
floorVertices.push_back(Point3d(20, 0, 0));
722
floorVertices.push_back(Point3d(20, 15, 0));
723
floorVertices.push_back(Point3d(0, 15, 0));
724

725
// Calculate floor area
726
Polygon3d floor(floorVertices);
727
boost::optional<double> area = floor.area();
728
if (area) {
729
  std::cout << "Floor area: " << *area << " m²" << std::endl;
730
}
731

732
// Transform geometry (rotate building 45 degrees)
733
Vector3d zAxis(0, 0, 1);
734
Transformation rotation = Transformation::rotation(zAxis, 45 * 3.14159 / 180);
735

736
std::vector<Point3d> rotatedVertices = rotation * floorVertices;
737
```
738

739
### Unit Conversions
740

741
```cpp
742
#include <openstudio/utilities/units/Quantity.hpp>
743
#include <openstudio/utilities/units/QuantityFactory.hpp>
744

745
using namespace openstudio;
746

747
// Create quantities with units
748
Quantity areaIP(1000, createUnits::createIPArea());  // 1000 ft²
749
Quantity areaSI(100, createUnits::createSIArea());   // 100 m²
750

751
// Convert between unit systems
752
boost::optional<Quantity> areaSIConverted = areaIP.convert(createUnits::createSIArea());
753
if (areaSIConverted) {
754
  std::cout << areaIP.value() << " ft² = " 
755
            << areaSIConverted->value() << " m²" << std::endl;
756
}
757

758
// Energy calculations
759
Quantity powerSI(5000, createUnits::createSIPower());  // 5000 W
760
Quantity timeHours(8, createUnits::createTime());      // 8 hours
761

762
Quantity energy = powerSI * timeHours;  // Energy in W⋅h
763
boost::optional<Quantity> energyKWh = energy.convert(createUnits::createKWh());
764

765
// Temperature conversions
766
Quantity tempF(75, createUnits::createFahrenheitTemperature());
767
boost::optional<Quantity> tempC = tempF.convert(createUnits::createCelsiusTemperature());
768
```
769

770
### Logging Operations
771

772
```cpp
773
#include <openstudio/utilities/core/Logger.hpp>
774

775
using namespace openstudio;
776

777
// Set up file logging
778
boost::shared_ptr<FileLogSink> fileSink(new FileLogSink(Path("simulation.log")));
779
fileSink->setLogLevel(LogLevel::Info);
780
Logger::instance().addLogSink(fileSink);
781

782
// Log messages at different levels
783
LOG_FREE(LogLevel::Info, "OpenStudio.Model", "Creating building model");
784
LOG_FREE(LogLevel::Warn, "OpenStudio.Model", "Missing construction assignment");
785
LOG_FREE(LogLevel::Error, "OpenStudio.Simulation", "EnergyPlus simulation failed");
786

787
// Log with channel filtering
788
boost::shared_ptr<StringStreamLogSink> testSink(new StringStreamLogSink());
789
testSink->setChannelRegex("OpenStudio\\.Model.*");
790
Logger::instance().addLogSink(testSink);
791
```