openstudio-analysis 0.3.7 → 0.4.0

data/lib/openstudio/analysis/workflow.rb

@@ -0,0 +1,197 @@
+# OpenStudio::Analysis::Workflow configured the list of measures to run and in what order
+module OpenStudio
+  module Analysis
+    class Workflow
+      attr_reader :items
+      # allow users to access the items via the measures attribute accessor
+      alias_method :measures, :items
+
+      # Create an instance of the OpenStudio::Analysis::Workflow
+      #
+      # @return [Object] An OpenStudio::Analysis::Workflow object
+      def initialize
+        @items = []
+      end
+
+      # Remove all the items in the workflow
+      def clear
+        @items.clear
+      end
+
+      # Add a measure to the workflow from a path. Inside the path it is expecting to have a measure.json file
+      # if not, the BCL gem is used to create the measure.json file.
+      #
+      # @params instance_name [String] The name of the instance. This allows for multiple measures to be added to the worklow with unique names
+      # @params instance_display_name [String] The display name of the instance. This allows for multiple measures to be added to the worklow with unique names
+      # @param path_to_measure [String] This is the local path to the measure directory, relative or absolute. It is used when zipping up all the measures.
+      # @return [Object] Returns the measure that was added as an OpenStudio::AnalysisWorkflowStep object
+      def add_measure_from_path(instance_name, instance_display_name, path_to_measure)
+        measure_filename = 'measure.rb'
+        if File.exist?(path_to_measure) && File.file?(path_to_measure)
+          measure_filename = File.basename(path_to_measure)
+          path_to_measure = File.dirname(path_to_measure)
+        end
+
+        if Dir.exist?(path_to_measure) && File.directory?(path_to_measure)
+          # Watch out for namespace conflicts (use ::BCL)
+          b = ::BCL::ComponentMethods.new
+          measure_hash = nil
+          unless File.exist?(File.join(path_to_measure, 'measure.json'))
+            measure_hash = b.parse_measure_file(nil, File.join(path_to_measure, measure_filename))
+            File.open(File.join(path_to_measure, 'measure.json'), 'w') { |f| f << JSON.pretty_generate(measure_hash) }
+            warn("measure.json not found in #{path_to_measure}, will parse measure file using BCL gem")
+          end
+
+          if measure_hash.nil? && File.exist?(File.join(path_to_measure, 'measure.json'))
+            measure_hash = JSON.parse(File.read(File.join(path_to_measure, 'measure.json')), symbolize_names: true)
+          elsif measure_hash.nil?
+            fail 'measure.json was not found and was not automatically created'
+          end
+
+          add_measure(instance_name, instance_display_name, path_to_measure, measure_hash)
+        else
+          fail "could not find measure to add to workflow #{path_to_measure}"
+        end
+
+        @items.last
+      end
+
+      # Add a measure from the custom hash format without reading the measure.rb or measure.json file
+      #
+      # @params instance_name [String] The name of the instance. This allows for multiple measures to be added to the worklow with unique names
+      # @params instance_display_name [String] The display name of the instance. This allows for multiple measures to be added to the worklow with unique names
+      # @param path_to_measure [String] This is the local path to the measure directory, relative or absolute. It is used when zipping up all the measures.
+      # @param measure_metadata [Hash] Format of the measure.json
+      # @return [Object] Returns the measure that was added as an OpenStudio::AnalysisWorkflowStep object
+      def add_measure(instance_name, instance_display_name, path_to_measure, measure_metadata)
+        @items << OpenStudio::Analysis::WorkflowStep.from_measure_hash(instance_name, instance_display_name, path_to_measure, measure_metadata)
+
+        @items.last
+      end
+
+      # Add a measure from the format that Excel parses into. This is a helper method to map the excel data to the new
+      # programmatic interface format
+      #
+      # @params measure [Hash] The measure in the format of the Excel translator
+      # @return [Object] Returns the measure that was added as an OpenStudio::AnalysisWorkflowStep object
+      def add_measure_from_excel(measure)
+        hash = {}
+        hash[:classname] = measure['measure_file_name']
+        hash[:name] = measure['name']
+        hash[:display_name] = measure['display_name']
+        hash[:measure_type] = measure['measure_type']
+        hash[:uid] = measure['uid'] ? measure['uid'] : SecureRandom.uuid
+        hash[:version_id] = measure['version_id'] ? measure['version_id'] : SecureRandom.uuid
+
+        # map the arguments - this can be a variable or argument, add them all as arguments first
+        args = []
+        measure['variables'].each do |variable|
+          args << {
+            local_variable: variable['name'],
+            variable_type: variable['type'],
+            name: variable['name'],
+            display_name: variable['display_name'],
+            display_name_short: variable['display_name_short'],
+            units: variable['units'],
+            default_value: variable['distribution']['static_value'],
+            value: variable['distribution']['static_value']
+          }
+        end
+        hash[:arguments] = args
+
+        m = add_measure(measure['name'], measure['display_name'], "./spec/files/measures/#{measure['measure_file_name_directory']}", hash)
+
+        measure['variables'].each do |variable|
+          next unless variable['variable_type'] == 'variable'
+
+          dist = {
+            type: variable['distribution']['type'],
+            minimum: variable['distribution']['min'],
+            maximum: variable['distribution']['max'],
+            mean: variable['distribution']['mean'],
+            standard_deviation: variable['distribution']['stddev'],
+            values: variable['distribution']['discrete_values'],
+            weights: variable['distribution']['discrete_weights'],
+            step_size: variable['distribution']['delta_x']
+          }
+          opt = {
+            variable_type: variable['variable_type'],
+            variable_display_name_short: variable['display_name_short'],
+            static_value: variable['distribution']['static_value']
+          }
+
+          m.make_variable(variable['name'], variable['display_name'], dist)
+        end
+      end
+
+      # Find the measure by its instance name
+      #
+      # @params instance_name [String] instance name of the measure
+      # @return [Object] The WorkflowStep with the instance_name
+      def find_measure(instance_name)
+        @items.find { |i| i.name == instance_name }
+      end
+      alias_method :find_workflow_step, :find_measure
+
+      # Return all the variables in the analysis as an array. The list that is returned is read only.
+      #
+      # @return [Array] All variables in the workflow
+      def all_variables
+        @items.map(&:variables).flatten
+      end
+
+      # Save the workflow to a hash object
+      def to_hash(version = 1)
+        h = nil
+        if version == 1
+          arr = []
+          @items.each_with_index do |item, index|
+            temp_h = item.to_hash(version)
+            temp_h[:workflow_index] = index
+
+            arr << temp_h
+          end
+
+          h = arr
+        else
+          fail "Version #{version} not yet implemented for to_hash"
+        end
+
+        h
+      end
+
+      # Save the workflow to a JSON string
+      #
+      # @return [String] JSON formatted string
+      def to_json(version = 1)
+        if version == 1
+          JSON.pretty_generate(to_hash(version))
+        else
+          fail "Version #{version} not yet implemented for to_json"
+        end
+      end
+
+      # Read the Workflow description from a persisted file. The format at the moment is the current analysis.json
+      #
+      # @params filename [String] Path to file with the analysis.json to load
+      # @return [Object] Return an instance of the workflow object
+      def self.from_file(filename)
+        if File.exist? filename
+          j = JSON.parse(File.read(filename), symbolize_names: true)
+
+          # get the version of the file
+          file_format_version = j[:file_format_version] ? j[:file_format_version] : 1
+
+          puts "Parsing file version #{file_format_version}"
+
+        else
+          fail "Could not find workflow file #{filename}"
+        end
+
+        o = OpenStudio::Analysis::Workflow.new
+        # put the JSON into the right format
+        o
+      end
+    end
+  end
+end

data/lib/openstudio/analysis/workflow_step.rb

@@ -0,0 +1,312 @@
+# OpenStudio::Analysis::WorkflowStep is a class container for storing a measure. The generic name of step may be used later
+# to include a workflow step on running EnergyPlus, radiance, etc.
+module OpenStudio
+  module Analysis
+    class WorkflowStep
+      attr_accessor :type
+      attr_accessor :name
+      attr_accessor :display_name
+
+      attr_accessor :measure_definition_class_name
+      attr_accessor :measure_definition_directory
+      attr_accessor :measure_definition_display_name
+      attr_accessor :measure_definition_name
+      attr_accessor :measure_definition_name_xml
+      attr_accessor :measure_definition_uuid
+      attr_accessor :measure_definition_version_uuid
+      attr_reader :arguments
+      attr_reader :variables
+
+      # Create an instance of the OpenStudio::Analysis::WorkflowStep
+      #
+      # @return [Object] An OpenStudio::Analysis::WorkflowStep object
+      def initialize
+        @name = ''
+        @display_name = ''
+
+        # The type of item being added (RubyMeasure, EnergyPlusMeasure, ...)
+        @type = nil
+
+        @measure_definition_class_name = nil
+        @measure_definition_directory = nil
+        @measure_definition_display_name = nil
+        @measure_definition_name = nil
+        @measure_definition_name_xml = nil
+        @measure_definition_uuid = nil
+        @measure_definition_version_uuid = nil
+        @arguments = []
+
+        # TODO: eventually the variables should be its own class. This would then be an array of Variable objects.
+        @variables = []
+      end
+
+      # Return an array of the argument names
+      #
+      # @return [Array] Listing of argument names.
+      def argument_names
+        @arguments.map { |a| a[:name] }
+      end
+
+      # Set the value of an argument to `value`. The user is required to know the data type and pass it in accordingly
+      #
+      # @param argument_name [String] The machine name of the argument that you want to set the value to
+      # @param value [] The value to assign the argument
+      # @return [Boolean] True/false if it assigned it
+      def argument_value(argument_name, value)
+        a = @arguments.find_all { |a| a[:name] == argument_name }
+        fail "could not find argument_name of #{argument_name} in measure #{name}" if a.empty?
+        fail "more than one argument with the same name of #{argument_name} in measure #{name}" if a.size > 1
+
+        a = a.first
+
+        a[:value] = value
+
+        a[:value] == value
+      end
+      # Tag a measure's argument as a variable.
+      #
+      # @param argument_name [String] The instance_name of the measure argument that is to be tagged. This is the same name as the argument's variable in the measure.rb file.
+      # @param variable_display_name [String] What the variable is called. It is best if the display name is self describing (i.e. does not need any other context). It can be the same as the argument display name.
+      # @param distribution [Hash] Hash describing the distribution of the variable.
+      # @option distribution [String] :type Type of distribution. `discrete`, `uniform`, `triangle`, `normal`, `lognormal`
+      # @option distribution [String] :units Units of the variable. This is legacy as previous OpenStudio measures did not specify units separately.
+      # @option distribution [String] :minimum Minimum value of the distribution, required for all distributions
+      # @option distribution [String] :maximum Maximum value of the distribution, required for all distributions
+      # @option distribution [String] :standard_deviation The standard deviation, if the distribution requires it.
+      # @option distribution [String] :mode The mean/mode of the distribution (if required)
+      # @option distribution [String] :mean Alias for the mode. If this is used it will override the mode
+      # @option distribution [String] :relation_to_output How is the variable correlates to the output of interest (for continuous distributions)
+      # @option distribution [String] :step_size Minimum step size (delta_x) of the variable (for continuous distributions)
+      # @option distribution [String] :values If discrete, then the values to run
+      # @option distribution [String] :weights If discrete, then the weights for each of the discrete values, must be the same length as values, and sum to 1. If empty, then it will create this automatically to be uniform.
+      # @param variable_type [String] What type of variable, variable or pivot. Typically this is variable.
+      # @param options [Hash] Values that define the variable.
+      # @option options [String] :variable_type The type of variable, `variable` or `pivot`. By default this is a variable.
+      # @option options [String] :variable_display_name_short The short display name of the variable. Will be defaulted to the variable_display_name if not passed
+      # @option options [String] :static_value Static/Default value of the variable. If not defined it will use the default value for the argument. This can be set later as well using the `argument_value` method.
+      # @return [Boolean] True / False if it was able to tag the measure argument
+      def make_variable(argument_name, variable_display_name, distribution, options = {})
+        options = { variable_type: 'variable' }.merge(options)
+        distribution[:mode] = distribution[:mean] if distribution.key? :mean
+
+        a = @arguments.find_all { |a| a[:name] == argument_name }
+        fail "could not find argument_name of #{argument_name} in measure #{name}" if a.empty?
+        fail "more than one argument with the same name of #{argument_name} in measure #{name}" if a.size > 1
+
+        if distribution_valid?(distribution)
+          # grab the argument hash
+          a = a.first
+
+          # add more information to the argument
+          v = {}
+          v[:argument] = a
+          v[:display_name] = variable_display_name
+          v[:display_name_short] = options[:variable_display_name_short] ? options[:variable_display_name_short] : variable_display_name
+
+          v[:type] = distribution[:type]
+          v[:units] = distribution[:units] ? distribution[:units] : nil
+          v[:minimum] = distribution[:minimum]
+          v[:maximum] = distribution[:maximum]
+          v[:relation_to_output] = distribution[:relation_to_output] ? distribution[:relation_to_output] : nil
+          v[:mode] = distribution[:mode]
+          v[:static_value] = distribution[:static_value] if distribution[:static_value]
+          # TODO: Static value should be named default value or just value
+
+          if distribution[:type] =~ /discrete/
+            v[:weights] = distribution[:weights]
+            v[:values] = distribution[:values]
+          elsif distribution[:type] =~ /uniform/
+            # all the data should be present
+          elsif distribution[:type] =~ /triangle/
+            v[:step_size] = distribution[:step_size] ? distribution[:step_size] : nil
+            # stddev is not saves when triangular
+          elsif distribution[:type] =~ /normal/
+            v[:step_size] = distribution[:step_size] ? distribution[:step_size] : nil
+            v[:standard_deviation] = distribution[:standard_deviation]
+          end
+
+          # assign uuid and version id to the variable
+          v[:uuid] = SecureRandom.uuid
+          v[:version_uuid] = SecureRandom.uuid
+          @variables << v
+        end
+        true
+      end
+
+      # Convert the class into a hash. TODO: Make this smart based on the :type eventually
+      #
+      # @return [Hash] Returns the hash
+      def to_hash(version = 1, *a)
+        hash = {}
+        if version == 1
+          instance_variables.each do |var|
+            if var.to_s == '@type'
+              hash[:measure_type] = instance_variable_get(var)
+            elsif var.to_s == '@arguments'
+              hash[:arguments] = []
+              @arguments.each do |a|
+                # This will change in version 2 but right now, if the argument is a variable, then the argument will
+                # be in the variables hash, not the arguments hash.
+                next unless @variables.find { |v| v[:argument][:name] == a[:name] }.nil?
+                hash[:arguments] << a
+              end
+            elsif var.to_s == '@variables'
+              # skip until after looping over instance_variables
+            elsif var.to_s == '@__swigtype__'
+              # skip the swig variables caused by using the same namespace as OpenStudio
+            else
+              hash[var.to_s.delete('@')] = instance_variable_get(var)
+            end
+
+            # TODO: warn that we are no longer writing out "variable_type": "RubyContinuousVariable",
+            # TODO: iterate over the variables and create UUIDs, or not?
+          end
+
+          # fix everything to support the legacy version
+          hash[:variables] = @variables
+
+          # Clean up the variables to match the legacy format
+          hash[:variables].each_with_index do |v, index|
+            v[:variable_type] == 'pivot' ? v[:pivot] = true : v[:variable] = true
+            v[:variable] = true
+            v[:static_value] = v[:argument][:default_value] unless v[:static_value]
+
+            v[:uncertainty_description] = {}
+            v[:uncertainty_description][:type] = v[:type] =~ /uncertain/ ? "#{v[:type]}" : "#{v[:type]}_uncertain"
+            warn "Deprecation Warning. In Version 0.5 the _uncertain text will be removed from distribution types: #{v[:uncertainty_description][:type]}"
+            warn 'Deprecation Warning. RubyContinuousVariable (OpenStudio called this the variable_type) is no longer persisted'
+
+            # This is not neatly coded. This should be a new object that knows how to write itself out.
+            v[:uncertainty_description][:attributes] = []
+            if v[:type] =~ /discrete/
+              new_h = {}
+              new_h[:name] = 'discrete'
+              new_h[:values_and_weights] = v.delete(:values).zip(v.delete(:weights)).map { |w| { value: w[0], weight: w[1] } }
+              v[:uncertainty_description][:attributes] << new_h
+
+              v[:uncertainty_description][:attributes] << { name: 'lower_bounds', value: v[:minimum] }
+              v[:uncertainty_description][:attributes] << { name: 'upper_bounds', value: v[:maximum] }
+              v[:uncertainty_description][:attributes] << { name: 'modes', value: v[:mode] }
+            elsif v[:type] =~ /uniform/
+              v[:uncertainty_description][:attributes] << { name: 'lower_bounds', value: v[:minimum] }
+              v[:uncertainty_description][:attributes] << { name: 'upper_bounds', value: v[:maximum] }
+              v[:uncertainty_description][:attributes] << { name: 'modes', value: v[:mode] }
+            else
+              v[:uncertainty_description][:attributes] << { name: 'lower_bounds', value: v[:minimum] }
+              v[:uncertainty_description][:attributes] << { name: 'upper_bounds', value: v[:maximum] }
+              v[:uncertainty_description][:attributes] << { name: 'modes', value: v[:mode] }
+              v[:uncertainty_description][:attributes] << { name: 'delta_x', value: v[:step_size] ? v[:step_size] : nil }
+              v[:uncertainty_description][:attributes] << { name: 'stddev', value: v[:standard_deviation] ? v[:standard_deviation] : nil }
+            end
+
+            v[:workflow_index] = index
+            warn 'Deprecation Warning. workflow_step_type is no longer persisted'
+
+            # remove some remaining items
+            v.delete(:type)
+            v.delete(:mode) if v.key?(:mode)
+            v.delete(:step_size) if v.key?(:step_size)
+            v.delete(:standard_deviation) if v.key?(:standard_deviation)
+          end
+
+        else
+          fail "Do not know how to create the Hash for Version #{version}"
+        end
+
+        hash
+      end
+
+      # Read the workflow item from a measure hash.
+      #
+      # @param instance_name [String] Machine name of the instance
+      # @param instance_display_name [String] Display name of the instance
+      # @param path_to_measure [String] This is the local path to the measure directroy, relative or absolute. It is used when zipping up all the measures.
+      # @param hash [Hash] Measure hash in the format of the measure.json (from the Analysis Spreadsheet project)
+
+      # @return [Object] Returns the OpenStudio::Analysis::WorkflowStep
+      def self.from_measure_hash(instance_name, instance_display_name, path_to_measure, hash)
+        # TODO: Validate the hash
+        # TODO: validate that the measure exists?
+
+        # verify that the path to the measure is a path and not a file.
+        if File.exist?(path_to_measure) && File.file?(path_to_measure)
+          path_to_measure = File.dirname(path_to_measure)
+        end
+
+        # map the BCL hash format into the OpenStudio WorkflowStep format
+        s = OpenStudio::Analysis::WorkflowStep.new
+
+        # add the instance and display name
+        s.name = instance_name
+        s.display_name = instance_display_name
+
+        # definition of the measure
+        s.measure_definition_class_name = hash[:classname]
+        s.measure_definition_directory = path_to_measure
+        s.measure_definition_display_name = hash[:display_name]
+        s.measure_definition_name = hash[:name]
+        # name_xml is not used right now but eventually should be used to compare the hash[:name] and the hash[:name_xml]
+        s.measure_definition_name_xml = hash[:name_xml]
+        s.measure_definition_uuid = hash[:uid]
+        s.measure_definition_version_uuid = hash[:version_id]
+
+        # do not allow the choice variable_type
+
+        s.type = hash[:measure_type] # this is actually the measure type
+        if hash[:arguments]
+          hash[:arguments].each do |arg|
+            var_type = arg[:variable_type].downcase
+            if var_type == 'choice'
+              # WARN the user that the measure had a "choice data type"
+              var_type = 'string'
+            end
+
+            s.arguments << {
+              display_name: arg[:display_name],
+              display_name_short: arg[:display_name],
+              name: arg[:local_variable],
+              value_type: var_type,
+              default_value: arg[:default_value],
+              value: arg[:default_value]
+            }
+          end
+        end
+
+        s
+      end
+
+      private
+
+      # validate the arguments of the distribution
+      def distribution_valid?(d)
+        # regardless of uncertainty description the following must be defined
+        fail 'No distribution defined for variable' unless d.key? :type
+        fail 'No minimum defined for variable' unless d.key? :minimum
+        fail 'No maximum defined for variable' unless d.key? :maximum
+        fail 'No mean/mode defined for variable' unless d.key? :mode
+
+        if d[:type] =~ /uniform/
+          # Do we need to tell the user that we don't really need the mean/mode for uniform?
+        elsif d[:type] =~ /discrete/
+          # require min, max, mode
+          fail 'No values passed for discrete distribution' unless d[:values] || d[:values].empty?
+          if d[:weights]
+            fail 'Weights are not the same length as values' unless d[:values].size == d[:weights].size
+            fail 'Weights do not sum up to one' unless d[:weights].reduce(:+).between?(0.99, 1.01) # allow a small error for now
+          else
+            fraction = 1 / d[:values].size.to_f
+            d[:weights] = [fraction] * d[:values].size
+          end
+        elsif d[:type] =~ /triangle/
+          # requires min, max, mode
+
+        elsif d[:type] =~ /normal/ # both normal and lognormal
+          # require min, max, mode, stddev
+          fail 'No standard deviation for variable' unless d[:standard_deviation]
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/openstudio/analysis.rb

@@ -0,0 +1,8 @@
+# OpenStudio::Analysis Module instantiates versions of formulations
+module OpenStudio
+  module Analysis
+    def self.create(display_name)
+      OpenStudio::Analysis::Formulation.new(display_name)
+    end
+  end
+end

data/lib/openstudio/helpers/string.rb

@@ -3,10 +3,10 @@
 class String
   def underscore
     gsub(/::/, '/')
-    .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-    .tr('-', '_')
-    .downcase
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr('-', '_')
+      .downcase
   end
 
   def snake_case
@@ -22,25 +22,25 @@ end
 
 def typecast_value(variable_type, value, inspect_string = false)
   out_value = nil
-  case variable_type.downcase
-    when 'double'
-      out_value = value.to_f
-    when 'integer'
-      out_value = value.to_i
-    when 'string'
-      out_value = inspect_string ? value.inspect : value.to_s
-    when 'choice'
-      out_value = value.inspect
-    when 'bool', 'boolean'
-      if value.downcase == 'true'
-        out_value = true
-      elsif value.downcase == 'false'
-        out_value = false
+  unless value.nil?
+    case variable_type.downcase
+      when 'double'
+        out_value = value.to_f
+      when 'integer'
+        out_value = value.to_i
+      when 'string', 'choice'
+        out_value = inspect_string ? value.inspect : value.to_s
+      when 'bool', 'boolean'
+        if value.downcase == 'true'
+          out_value = true
+        elsif value.downcase == 'false'
+          out_value = false
+        else
+          fail "Can't cast to a bool from a value of '#{value}' of class '#{value.class}'"
+        end
       else
-        fail "Can't cast to a bool from a value of '#{value}' of class '#{value.class}'"
-      end
-    else
-      fail "Unknown variable type of '#{@variable['type']}'"
+        fail "Unknown variable type of '#{@variable['type']}'"
+    end
   end
 
   out_value

data/lib/openstudio/templates/analysis.json.erb

@@ -6,7 +6,6 @@
         "problem": {
             "algorithm": {
             },
-            "name": "Problem",
             "workflow": []
         },
         "seed": {

data/lib/openstudio-analysis.rb

@@ -12,10 +12,19 @@ require 'zip'
 require 'semantic'
 require 'semantic/core_ext'
 
+require 'bcl'
+
 # core
 require 'openstudio/analysis/server_api'
 require 'openstudio/analysis/version'
 
+# analysis classes
+require 'openstudio/analysis'
+require 'openstudio/analysis/formulation'
+require 'openstudio/analysis/workflow'
+require 'openstudio/analysis/workflow_step'
+require 'openstudio/analysis/algorithm_attributes'
+
 # translators
 require 'openstudio/analysis/translator/excel'