alfalfa-lib 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ed2dabb03d5554d08b9d59d60c6a428a558e003ae35ce9b8e82c3f6bd51f0c9
+  data.tar.gz: bc789596938cecc94e6b16f99ac20a3a65b03153a5dee380907f79823b604d80
+SHA512:
+  metadata.gz: 7be3f7dadf87b569b097a2ff283bbceed8925abbf786e9ba7829713c7d428938d914034b60cb561d818b3513218e337d3de904d3a4a5d7386b00d55bb611a047
+  data.tar.gz: 625097e38f00189cd1c0bc44b7665cd44e4d8b995b5e34d656f4c3b5c493d4fbb1bd7da928cd2dd45bdc8f908f691da209548bf1acea98965382a23e02d2b277

data/lib/alfalfa.rb

@@ -0,0 +1,13 @@
+require 'alfalfa_mixin'
+require 'energy_plus_mixin'
+require 'input'
+require 'openstudio_mixin'
+require 'output'
+require 'point'
+
+# Module which contains all OpenStudio code
+module OpenStudio
+  # Module which contains Alfalfa specific functionality
+  module Alfalfa
+  end
+end

data/lib/alfalfa_mixin.rb

@@ -0,0 +1,99 @@
+require_relative 'utils'
+module OpenStudio
+  module Alfalfa
+    ##
+    # Base mixin for managing alfalfa points
+    #
+    module AlfalfaMixin
+      include OpenStudio::Alfalfa::Utils
+      # Create reports of input and outputs for alfalfa
+      # Must be executed at the end of the measure to expose points in alfalfa
+      def report_inputs_outputs
+        @inputs.each do |input|
+          next if input.echo.nil?
+          next if @outputs.include? input.echo
+
+          @outputs.append(input.echo)
+        end
+
+        inputs_dict = {}
+        outputs_dict = {}
+        @inputs.each do |input|
+          hash = input.to_dict
+          inputs_dict[hash['id']] = hash
+        end
+        @outputs.each do |output|
+          hash = output.to_dict
+          outputs_dict[hash['id']] = hash
+        end
+
+        File.open('./report_inputs.json', 'w') do |f|
+          JSON.dump(inputs_dict, f)
+        end
+        File.open('./report_outputs.json', 'w') do |f|
+          JSON.dump(outputs_dict, f)
+        end
+      end
+
+      # Register an input for inclusion in alfalfa
+      #
+      # @param [IdfObject, ModelObject, Input] input to register
+      # May be:
+      # - ExternalInterface:Actuator
+      # - ExternalInterface:Variable
+      # - ExternalInterface:Schedule
+      # - OS:ExternalInterface:Variable
+      # - OS:ExternalInterface:Schedule
+      # - OS:ExternalInterface:Actuator
+      # or:
+      # - OpenStudio::Alfalfa::Input
+      #
+      # @return [Input]
+      def register_input(input)
+        if input.is_a? OpenStudio::Alfalfa::Input
+          @inputs.append(input)
+        else
+          input = OpenStudio::Alfalfa::Input.new(input)
+          register_input(input)
+        end
+        input
+      end
+
+      # Find an input by it's associated object name
+      #
+      # @param [String] name Name of input to find
+      #
+      # @return [Input]
+      def get_input_by_name(name)
+        @inputs.each do |input|
+          next unless input.object.name.get == name
+
+          return input
+        end
+        nil
+      end
+
+      # Register an output for inclusion in alfalfa
+      #
+      # @param output [IdfObject, ModelObject, Output] output to register
+      # May be:
+      # - Output:Variable
+      # - EnergyManagementSystem:OutputVariable
+      # - OS:Output:Variable
+      # - OS:EnergyManagementSystem:OutputVariable
+      # or:
+      # - OpenStudio::Alfalfa::Output
+      #
+      # @return [Output]
+      def register_output(output)
+        if output.is_a? OpenStudio::Alfalfa::Output
+          @outputs.append(output)
+        else
+          output = OpenStudio::Alfalfa::Output.new(output)
+          register_output(output)
+        end
+        output
+      end
+    end
+  end
+end

data/lib/energy_plus_mixin.rb

@@ -0,0 +1,167 @@
+require_relative 'alfalfa_mixin'
+require_relative 'utils'
+module OpenStudio
+  module Alfalfa
+    ##
+    # EnergyPlusMixin
+    #
+    # Mixin to include when developing an EnergyPlus Measure
+    module EnergyPlusMixin
+      include OpenStudio::Alfalfa::AlfalfaMixin
+      include OpenStudio::Alfalfa::Utils
+
+      # Get first node from NodeList
+      #
+      # @param [String] node NodeList id
+      def get_node_from_nodelist(node)
+        node_list_object = @workspace.getObjectByTypeAndName('NodeList'.to_IddObjectType, node)
+        return node_list_object.get.getField(1).get if node_list_object.is_initialized
+
+        node
+      end
+
+      # Create Output Variable
+      #
+      # @param [String] key Key of Output Variable
+      # @param [String] var Variable of Output Variable
+      #
+      # @return [Output]
+      def create_output_variable(key, var)
+        output_variable_string = "
+        Output:Variable,
+          #{key},
+          #{var},
+          Timestep;"
+        output_variable_object = OpenStudio::IdfObject.load(output_variable_string).get
+        OpenStudio::Alfalfa::Output.new(@workspace.addObject(output_variable_object).get)
+      end
+
+      # Create EMS Output Variable
+      #
+      # @param [String] name Name of EMS Output Variable to create
+      # @param [String] variable EMS name of variable to connect to Output Variable
+      # @param [String] unit Unit of output
+      #
+      # @return [Output]
+      def create_ems_output_variable(name, variable, unit = 'C')
+        output_variable_string = "
+        EnergyManagementSystem:OutputVariable,
+          #{name},
+          #{variable},
+          Averaged,
+          SystemTimestep,
+          ,
+          #{unit};"
+        output_variable_object = OpenStudio::IdfObject.load(output_variable_string).get
+        OpenStudio::Alfalfa::Output.new(@workspace.addObject(output_variable_object).get)
+      end
+
+      # Create External Interface Variable
+      #
+      # @param [String] name Name of external variable to create
+      # @param [Number] initial_value Initial value of external variable
+      #
+      # @return [Input]
+      def create_external_variable(name, initial_value = 0)
+        new_external_variable_string = "
+        ExternalInterface:Variable,
+          #{create_ems_str(name)},             !- Name,
+          #{initial_value};    !- Initial value
+          "
+        new_external_variable_object = OpenStudio::IdfObject.load(new_external_variable_string).get
+        input = OpenStudio::Alfalfa::Input.new(@workspace.addObject(new_external_variable_object).get)
+        input.display_name = name
+        input
+      end
+
+      # Create enabled input to actuate an EMS variable.
+      # This method creates an external variable with the specified name
+      # and an EMS program to copy the value to the specified variable if enabled
+      # or the default value otherwise
+      #
+      # @param [String] name Name of input to create
+      # @param [String] variable_name EMS name of variable to control
+      # @param [String] default Value to have when not enabled. Default to null for actuator control
+      #
+      # @return [Input]
+      def create_enabled_input(name, variable_name, default = 'Null')
+        program_name = create_ems_str("#{name}_program")
+        alfalfa_input = create_external_variable(name)
+        enable_name = create_ems_str("#{name}_Enable")
+        alfalfa_input_enable = create_external_variable(enable_name)
+        new_program_string = "
+        EnergyManagementSystem:Program,
+          #{program_name},           !- Name
+          IF #{enable_name},
+          SET #{variable_name} = #{name},
+          ELSE,
+          SET #{variable_name} = #{default},
+          ENDIF;
+          "
+        new_program_object = OpenStudio::IdfObject.load(new_program_string).get
+        @workspace.addObject(new_program_object)
+        register_program(program_name)
+        alfalfa_input.enable_variable = alfalfa_input_enable
+        alfalfa_input
+      end
+
+      # Create actuator
+      #
+      # @param name [String] Name of actuator to create
+      # @param component [String] Name of component to actuate
+      # @param component_type [String] Type of component
+      # @param control_type[String] Type of control
+      # @param external [Boolean] When true an external interface variable with {name} will be created and returned
+      #
+      # @return [IdfObject, Input]
+      def create_actuator(name, component, component_type, control_type, external = false)
+        if external
+          actuator_name = create_ems_str("#{name}_actuator")
+          actuator_object = create_actuator(actuator_name, component, component_type, control_type)
+          input = create_enabled_input(name, actuator_name)
+          input.actuator = actuator_object
+          echo_name = create_ems_str("#{actuator_name}_echo")
+          output = create_ems_output_variable(echo_name, actuator_name)
+          input.echo = output
+          input
+        else
+          new_actuator_string = "
+          EnergyManagementSystem:Actuator,
+            #{name},                 !- Name
+            #{component},            !- Actuated Component Unique Name
+            #{component_type},       !- Actuated Component Type
+            #{control_type};         !- Actuated Component Control Type
+            "
+          new_actuator_object = OpenStudio::IdfObject.load(new_actuator_string).get
+          @workspace.addObject(new_actuator_object).get
+        end
+      end
+
+      def create_calling_point
+        new_calling_manager_string = "
+        EnergyManagementSystem:ProgramCallingManager,
+          #{create_ems_str(name)}_calling_point,          !- Name
+          EndOfZoneTimestepBeforeZoneReporting;    !- EnergyPlus Model Calling Point
+          "
+        new_calling_manager_object = OpenStudio::IdfObject.load(new_calling_manager_string).get
+        @calling_point_manager = @workspace.addObject(new_calling_manager_object).get
+        @program_count = 0
+      end
+
+      def register_program(program_name)
+        create_calling_point if @calling_point_manager.nil?
+
+        @calling_point_manager.setString(2 + @program_count, program_name)
+        @program_count += 1
+      end
+
+      def run(workspace, runner, user_arguments)
+        super(workspace, runner, user_arguments)
+        @workspace = workspace
+        @calling_point_manager = nil
+        @inputs = []
+        @outputs = []
+      end
+    end
+  end
+end

data/lib/input.rb

@@ -0,0 +1,72 @@
+require 'securerandom'
+require_relative 'utils'
+require_relative 'point'
+module OpenStudio
+  module Alfalfa
+    ##
+    # Input
+    #
+    # Class which represents an Input point to Alfalfa
+    class Input < Point
+      include OpenStudio::Alfalfa::Utils
+      attr_reader :input_object
+
+      def initialize(input_object)
+        super(input_object)
+
+        input_type = get_idd_type(input_object)
+        name = input_object.name.get
+
+        case input_type
+        when 'ExternalInterface:Actuator'.to_IddObjectType
+          @hash['actuator'] = name
+          self.actuator = input_object
+        when 'ExternalInterface:Variable'.to_IddObjectType
+          @hash['variable'] = name
+        when 'ExternalInterface:Schedule'.to_IddObjectType
+          @hash['schedule'] = name
+        when 'OS:ExternalInterface:Variable'.to_IddObjectType
+          @hash['variable'] = name
+        when 'OS:ExternalInterface:Schedule'.to_IddObjectType
+          @hash['schedule'] = name
+        when 'OS:ExternalInterface:Actuator'.to_IddObjectType
+          @hash['actuator'] = name
+          self.actuator = input_object
+        else
+          raise "#{input_type.valueDescription} is not a valid input type"
+        end
+        self.display_name = name
+      end
+
+      def actuator=(actuator_object)
+        actuator_type = get_idd_type(actuator_object)
+
+        actuator_types = ['ExternalInterface:Actuator'.to_IddObjectType,
+                          'OS:EnergyManagementSystem:Actuator'.to_IddObjectType,
+                          'EnergyManagementSystem:Actuator'.to_IddObjectType]
+
+        unless actuator_types.include? actuator_type
+          raise "#{actuator_type.valueDescription} is not a valid actuator type"
+        end
+
+        @hash['actuated_component'] = actuator_object.getString(1).get
+        @hash['actuated_component_type'] = actuator_object.getString(2).get
+        @hash['actuated_component_control_type'] = actuator_object.getString(3).get
+      end
+
+      def enable_variable=(enable_variable)
+        enable_variable = enable_variable.object if enable_variable.instance_of? OpenStudio::Alfalfa::Input
+
+        enable_variable_type = get_idd_type(enable_variable)
+        enable_variable_types = ['ExternalInterface:Variable'.to_IddObjectType,
+                                 'OS:ExternalInterface:Variable'.to_IddObjectType]
+
+        unless enable_variable_types.include? enable_variable_type
+          raise "#{enable_variable_type.valueDescription} is an invalid enable variable type"
+        end
+
+        @hash['enable_variable'] = enable_variable.name.get
+      end
+    end
+  end
+end

data/lib/openstudio_mixin.rb

@@ -0,0 +1,117 @@
+require 'alfalfa_mixin'
+module OpenStudio
+  module Alfalfa
+    ##
+    # OpenStudioMixin
+    #
+    # Mixin to include when developing an Model Measure
+    module OpenStudioMixin
+      include OpenStudio::Alfalfa::AlfalfaMixin
+
+      # Create Output Variable
+      #
+      # @param [String] key Key of Output Variable
+      # @param [String] var Variable of Output Variable
+      #
+      # @return [Output]
+      def create_output_variable(key, var)
+        output_variable = OpenStudio::Model::OutputVariable.new(create_ems_str("#{key}_#{var}"), @model)
+        output_variable.setKeyValue(key)
+        output_variable.setVariableName(var)
+
+        OpenStudio::Alfalfa::Output.new(output_variable)
+      end
+
+      # Create EMS Output Variable
+      #
+      # @param [String, ModelObject] variable EMS name of variable to connect to Output Variable
+      # @param [String] unit Unit of output
+      #
+      # @return [Output]
+      def create_ems_output_variable(variable, unit = 'C')
+        output_variable = OpenStudio::Model::EnergyManagementSystemOutputVariable.new(@model, variable)
+        output_variable.setUnits(unit)
+        Output.new(output_variable)
+      end
+
+      # Create External Interface Variable
+      #
+      # @param [String] name Name of external variable to create
+      # @param [Number] initial_value Initial value of external variable
+      #
+      # @return [Input]
+      def create_external_variable(name, initial_value = 0)
+        external_variable = OpenStudio::Model::ExternalInterfaceVariable.new(@model, create_ems_str(name),
+                                                                             initial_value)
+        external_variable.setExportToBCVTB(false)
+        Input.new(external_variable)
+      end
+
+      # Create enabled input to actuate an EMS variable.
+      # This method creates an external variable with the specified name
+      # and an EMS program to copy the value to the specified variable if enabled
+      # or the default value otherwise
+      #
+      # @param [String] name Name of input to create
+      # @param [String] variable_name EMS name of variable to control
+      # @param [String] default Value to have when not enabled. Default to null for actuator control
+      #
+      # @return [Input]
+      def create_enabled_input(name, variable_name, default = 'Null')
+        alfalfa_input = create_external_variable(name)
+        enable_name = create_ems_str("#{name}_Enable")
+        alfalfa_input_enable = create_external_variable(enable_name)
+        new_program = OpenStudio::Model::EnergyManagementSystemProgram.new(@model)
+        new_program.setLines(["IF #{enable_name},",
+                              "SET #{variable_name} = #{name},",
+                              'ELSE,',
+                              "SET #{variable_name} = #{default},",
+                              'ENDIF'])
+        register_program(new_program)
+        alfalfa_input.enable_variable = alfalfa_input_enable
+        alfalfa_input
+      end
+
+      # Create actuator
+      #
+      # @param name [String] Name of actuator to create
+      # @param component [ModelObject] component to actuate
+      # @param component_type[String] Type of component
+      # @param control_type [String] Type of control
+      # @param external [Boolean] When true an external interface variable with {name} will be created and returned
+      #
+      # @return [ModelObject, Input]
+      def create_actuator(name, component, component_type, control_type, external = false)
+        if external
+          actuator_name = create_ems_str("#{name}_actuator")
+          actuator_object = create_actuator(actuator_name, component, component_type, control_type)
+          input = create_enabled_input(name, actuator_name)
+          input.actuator = actuator_object
+          output = create_ems_output_variable(actuator_object)
+          input.echo = output
+          input
+        else
+          OpenStudio::Model::EnergyManagementSystemActuator.new(component, component_type, control_type)
+        end
+      end
+
+      def create_calling_point
+        @calling_point_manager = OpenStudio::Model::EnergyManagementSystemProgramCallingManager.new(@model)
+        @calling_point_manager.setCallingPoint('EndOfZoneTimestepBeforeZoneReporting')
+      end
+
+      def register_program(program)
+        create_calling_point if @calling_point_manager.nil?
+        @calling_point_manager.addProgram(program)
+      end
+
+      def run(model, runner, user_arguments)
+        super(model, runner, user_arguments)
+        @model = model
+        @calling_point_manager = nil
+        @inputs = []
+        @outputs = []
+      end
+    end
+  end
+end

data/lib/output.rb

@@ -0,0 +1,48 @@
+require 'securerandom'
+require 'openstudio'
+require_relative 'utils'
+require_relative 'point'
+module OpenStudio
+  module Alfalfa
+    ##
+    # Output
+    #
+    # Class which represents an Output point to Alfalfa
+    class Output < Point
+      include OpenStudio::Alfalfa::Utils
+      def initialize(output_object)
+        super(output_object)
+        output_type = get_idd_type(@object)
+
+        case output_type
+        when 'Output:Variable'.to_IddObjectType
+          @hash['component'] = @object.getString(0).get
+          @hash['variable'] = @object.getString(1).get
+        when 'EnergyManagementSystem:OutputVariable'.to_IddObjectType
+          @hash['component'] = 'EMS'
+          self.display_name = @object.name.get
+          @hash['variable'] = @object.getString(0).get
+          self.units = @object.getString(5).get
+        when 'OS:Output:Variable'.to_IddObjectType
+          @hash['component'] = @object.keyValue
+          @hash['variable'] = @object.variableName
+          self.display_name = @object.name.get
+        when 'OS:EnergyManagementSystem:OutputVariable'.to_IddObjectType
+          @hash['component'] = 'EMS'
+          @hash['variable'] = @object.name.get
+          self.display_name = @object.name.get
+        else
+          raise "#{output_type.valueDescription} is not a valid output type"
+        end
+      end
+
+      def component
+        @hash['component']
+      end
+
+      def variable
+        @hash['variable']
+      end
+    end
+  end
+end

data/lib/point.rb

@@ -0,0 +1,71 @@
+require 'securerandom'
+module OpenStudio
+  module Alfalfa
+    ##
+    # Point
+    # Base type for input and output point in alfalfa
+    class Point
+      attr_reader :echo, :object
+
+      # @param [IdfObject, ModelObject] object
+      def initialize(object)
+        @hash = {}
+        @hash['id'] = SecureRandom.uuid
+        @object = object
+      end
+
+      # Unique identifier of point
+      #
+      # @return [String]
+      def id
+        @hash['id']
+      end
+
+      # Display name used by Alfalfa
+      #
+      # @return [String]
+      def display_name
+        @hash['display_name']
+      end
+
+      def display_name=(display_name)
+        @hash['display_name'] = display_name
+      end
+
+      def echo=(output)
+        @echo = output
+        @hash['echo_id'] = output.id
+      end
+
+      def units=(units)
+        @hash['units'] = units
+      end
+
+      # Units for point
+      #
+      # @return [String]
+      def units
+        @hash['units']
+      end
+
+      # Add zone that point is related to
+      #
+      # @param zone [String]
+      def add_zone(zone)
+        if @hash.key? 'zone'
+          @hash['zone'].append(zone)
+        else
+          @hash['zone'] = [zone]
+        end
+      end
+
+      # Get dictionary of point
+      # This is used when compiling reports
+      #
+      # @return [Hash]
+      def to_dict
+        @hash
+      end
+    end
+  end
+end

data/lib/utils.rb

@@ -0,0 +1,36 @@
+require 'openstudio'
+module OpenStudio
+  module Alfalfa
+    ##
+    # This module provides utility functions
+    # for alfalfa and openstudio
+    module Utils
+      # Get Idd Type
+      # get the Idd type of objects in either an OSW of IDF context
+      #
+      # @param [ModelObject, IdfObject] object Object to get type of
+      #
+      # @return [IddType]
+      def get_idd_type(object)
+        if object.is_a? OpenStudio::Model::ModelObject
+          object.iddObjectType
+        elsif object.is_a? OpenStudio::IdfObject
+          object.iddObject.type
+        else
+          raise "cannot get idd_type of #{object.class}"
+        end
+      end
+
+      # return string formatted with no spaces or '-' (can be used as EMS var name)
+      # strings beginning with numbers will be prepended with '_'
+      # @param [String] id String to process into an EMS valid string
+      #
+      # @return [String]
+      def create_ems_str(id)
+        id = id.gsub(/[\s-]/, '_')
+        id = "_#{id}" if (id =~ /[0-9].*/) == 0
+        id
+      end
+    end
+  end
+end

data/lib/version.rb

@@ -0,0 +1,6 @@
+module OpenStudio
+  module Alfalfa
+    # Alfalfa Gem Version
+    VERSION = '0.0.0'.freeze
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: alfalfa-lib
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Tobias Shapinsky
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-07-25 00:00:00.000000000 Z
+dependencies: []
+description: Library and measures to create input and output points in Alfalfa
+email:
+- tobias.shapinsky@nrel.gov
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/alfalfa.rb
+- lib/alfalfa_mixin.rb
+- lib/energy_plus_mixin.rb
+- lib/input.rb
+- lib/openstudio_mixin.rb
+- lib/output.rb
+- lib/point.rb
+- lib/utils.rb
+- lib/version.rb
+homepage: https://github.com/NREL/alfalfa
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Create input and output points in Aflalfa
+test_files: []