OpenStudio Documentation

The OpenStudio Ruby implementation is composed of four distinct layers depending on your integration needs:

1. interpreter: The base Ruby interpreter with minimal OpenStudio initializations. It is provided via two CMake targets:
   • rubyinterpreter-declarations: An interface library that adds Ruby to the include path (used by standalone bindings).
   • rubyinterpreter: Adds Ruby to include paths and links to the Ruby library (used by the OpenStudio Ruby engine).
2. bindings: The interface used to initialize OpenStudio API bindings for Ruby (e.g., init_openstudio_model). This is consumed by both the module and engine components.
3. module: The standard OpenStudio Ruby bindings designed to be loaded into a standalone Ruby interpreter.
4. engine: A complete package combining the Ruby bindings, the Ruby interpreter, and embedded files. This is specifically designed for use by the OpenStudio CLI to execute Ruby-based workflows.

OpenStudio uses a hybrid naming convention because much of the Ruby API is generated from C++ via SWIG. When writing code for OpenStudio, follow these rules to distinguish between C++-style bindings and pure Ruby code:

• Top-level Module: Always use OpenStudio.
• Classes: Use UpperCamelCase (e.g., DetailedGeometry).
• C++-style Member Functions/Variables: Use lowerCamelCase (e.g., addVertex, timeOfDay). These are typically the SWIG-generated bindings.
• Pure Ruby Member Functions/Variables: Use snake_case (e.g., add_vertex_ruby, time_of_day_ruby).
• Enumerations: Use snake_case and symbols (e.g., enum items{:small_items, :big_items}).
• Getters: Do not start function names with get_ unless the function accepts one or more arguments.
• Unit Tests:
  • Test cases: UpperCamelCase post-fixed with _test (e.g., GeometryTest).
  • Individual tests: UpperCamelCase prefixed with test_ (e.g., test_vertex_addition).

Use const to provide compile-time guarantees and improve code safety:

• Variables: Use const for any value that should not be modified.
• Methods: Declare "getter" methods as const if they do not modify object data.
• Containers: For custom containers, provide both const and non-const versions of accessors (like operator[]) to ensure usability in different contexts.

Avoid these anti-patterns:

• Do not overload functions based on the const-ness of input arguments (e.g., void doSomething(const std::vector<int> &p) and void doSomething(std::vector<int> &p)).
• Do not implement both const and non-const versions of templated types unless strictly necessary.
• Avoid unnecessary const overloads for methods that return pointers (e.g., prefer std::shared_ptr<Data> Class::getData() const over providing both const and non-const versions).

class MyType
{
 public:
  int value() const; // const getter
  void setValue(int t_value); // non-const setter
 private:
  int m_value;
};

OpenStudio uses a connection model that differs significantly from EnergyPlus. While EnergyPlus connects components using shared unique node names, OpenStudio uses explicit OS:Connection objects to join Ports between components.

Key Concepts:

• Ports: Every HVAC component has inlets and outlets called Ports. These are identified by an index (e.g., port "5", port "6").
• OS:Connection: An object that references a Source Object and its Outlet Port, and a Target Object and its Inlet Port. This allows for arbitrary connections between any two components.
• OS:Node: In OpenStudio, a Node is a component type itself within the HVAC topology, rather than just a name. While most connections involve an intermediate OS:Node, it is not strictly required; components can be connected directly via an OS:Connection.

// EnergyPlus (Node-based)
Coil:Heating:Fuel, ..., Node 19, Node 20, ...;
Fan:ConstantVolume, ..., Node 20, Node 12, ...;

// OpenStudio (Connection-based)
OS:Connection,
  {connection-handle}, !- Handle
  {connection-name}, !- Name
  {source-handle},   !- Source Object
  6,                 !- Outlet Port
  {target-handle},   !- Target Object
  2;                 !- Inlet Port