amee-data-abstraction 1.0.0

data/lib/amee-data-abstraction/terms_list.rb

@@ -0,0 +1,150 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::TermsList
+
+module AMEE
+  module DataAbstraction
+
+    # Class extending the <i>Array</i> and providing specific attributes and
+    # methods for operating on a collection of instances of the class <i>Term</i>.
+    #
+    class TermsList < Array
+
+      # Subclasses of the <i>Term</i> class which <tt>self</tt> can contain.
+      #
+      # Each subclass symbol also represents a dynamically generated method name
+      # for <tt>self</tt> which can be called to return a new <tt>TermsList</tt>
+      # instance containing that subset of terms only, e.g.,
+      # 
+      #  my_terms_list.inputs               #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      #  my_terms_list.profiles             #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      # These methods can be compounded:
+      #
+      #  my_terms_list.inputs.drills        #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      #  my_terms_list.profiles.visible     #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      TermClasses= [:profiles,:drills,:inputs,:outputs,:metadata,:usages]
+
+      TermClasses.each do |term|
+        define_method(term) do
+          self.class.new select{|x|x.is_a? AMEE::DataAbstraction::const_get(term.to_s.singularize.classify)}
+        end
+      end
+
+      # Boolean attributes of instances of the <i>Term</i> class.
+      #
+      # Each attribute symbol also represents a dynamically generated method name
+      # for <tt>self</tt> which can be called to return a new <tt>TermsList</tt>
+      # instance containing that subset of only those terms for which the attribute
+      # is true, e.g.,
+      #
+      #   my_terms_list.visible             #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      #   my_terms_list.set                 #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      # These methods can be compounded:
+      #
+      #   my_terms_list.drills.visible.set  #=> <AMEE::DataAbstraction::TermsList ... >
+      #
+      TermFlags=[:set,:unset,:visible,:hidden,:fixed,
+        :optional,:compulsory,:enabled,:disabled,:drop_down,:text_box,:date]
+
+      TermFlags.each do |term|
+        define_method(term) do
+           self.class.new select{|x|x.send("#{term}?".to_sym)}
+        end
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms
+      # which occur before the term labeled <tt>label</tt> in the owning
+      # calculation
+      #
+      def before(label)
+        self.class.new select{|x|x.before?(label)}
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms
+      # which occur after the term labeled <tt>label</tt> in the owning
+      # calculation
+      #
+      def after(label)
+        self.class.new select{|x|x.after?(label)}
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms 
+      # which are optional in the owning calculation. 
+      # 
+      # If no argument is provided, the optional status of each term is defined 
+      # according to the current usage of the parent caluclation. Otherwise, 
+      # optional status is determined on the basis of the usage whose AMEE 
+      # platform path matches <tt>usage</tt>
+      #
+      def optional(usage=nil)
+        self.class.new select{|x|x.optional?(usage)}
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms
+      # which are compulsory in the owning calculation.
+      #
+      # If no argument is provided, the compulsory status of each term is defined
+      # according to the current usage of the parent caluclation. Otherwise,
+      # compulsory status is determined on the basis of the usage whose AMEE
+      # platform path matches <tt>usage</tt>
+      #
+      def compulsory(usage=nil)
+        self.class.new select{|x|x.compulsory?(usage)}
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms
+      # which are either compulsory OR optional in the owning calculation, i.e.
+      # any which are NOT forbidden.
+      #
+      # If no argument is provided, the optional/compulsory status of each term
+      # is defined according to the current usage of the parent caluclation.
+      # Otherwise, optional/compulsory status is determined on the basis of the
+      # usage whose AMEE platform path matches <tt>usage</tt>
+      #
+      def in_use(usage=nil)
+        self.class.new select{|x|x.in_use?(usage)}
+      end
+
+      # Return a new <tt>TermsList</tt> instance containing that subset of terms
+      # which are neither compulsory OR optional in the owning calculation, i.e.
+      # those which are forbidden.
+      #
+      # If no argument is provided, the forbidden status of each term is defined
+      # according to the current usage of the parent caluclation. Otherwise,
+      # forbidden status is determined on the basis of the usage whose AMEE
+      # platform path matches <tt>usage</tt>
+      #
+      def out_of_use(usage=nil)
+        self.class.new select{|x|x.out_of_use?(usage)}
+      end
+      
+      Selectors=TermClasses+TermFlags+[:before,:after,:optional,
+        :compulsory,:in_use,:out_of_use]
+
+      # Attributes of the class <i>Term</tt>.
+      # 
+      # Each attribute symbol also defines a dynamically generated method which
+      # return arrays of the values of the named attribute for all terms, e.g.,
+      # 
+      #   my_terms_list.labels => [ :type, :fuel, :distance, :co2 ... ]
+      #   
+      #   my_terms_list.values => [ 'van;, 'petrol', 500, 25.4 ... ]
+      #
+      TermProperties=[:label,:name,:path,:value,:unit,:per_unit,:default_unit,:default_per_unit]
+
+      TermProperties.each do |term|
+        define_method(term.to_s.pluralize.to_sym) do
+          map{|x|x.send(term)}
+        end
+      end
+
+    end
+  end
+end

data/lib/amee-data-abstraction/usage.rb

@@ -0,0 +1,90 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::Usage
+
+module AMEE
+  module DataAbstraction
+    
+    # Subclass of <tt>Input</tt> providing methods and attributes appropriate for
+    # representing adjustable calculation usages specifically.
+    # 
+    # Only one instance of <i>Usage</i> can be assocaited with a particular
+    # calucaltion object. When the value of <tt>self</tt> is changed, profile
+    # item value terms which are forbidden in the new usage will be inactivated
+    # and optional/compulsory flags are set on the remaining terms.
+    #
+    class Usage < Input
+
+      # Initialization of <i>Usage</i> objects follows that of the parent
+      # <i>Input</i> class, with a number of differences.
+      #
+      # If the parent caluclation already contains a usage term, a <i>TwoUsages</i>
+      # exception is raised.
+      #
+      # The <tt>label<tt> attribute is set by default to <tt>:usage</tt>.
+      #
+      # The <tt>interface</tt> attribute of <tt>self</tt> is set to
+      # <tt>:drop_down</tt> by default, but can be manually configured if
+      # required.
+      #
+      # The <tt>inactive</tt> property of <tt>self</tt> is set to <tt>:invisible</tt>
+      # by default.
+      #
+      def initialize(options={},&block)
+        raise Exceptions::TwoUsages if options[:parent].current_usage
+        label :usage
+        @inactive=:invisible
+        super
+        interface :drop_down unless interface
+      end
+
+      # Represents the method of handling forbidden terms. Should they be hidden
+      # in generated UIs or just disabled (greyed out)? Set the behaviour by
+      # passing either <tt>:invisible</tt> or <tt>:disabled</tt> as an argument. 
+      # Retrieve the defined behaviour by calling without an argument.
+      #
+      attr_property :inactive
+
+      # Adjust the value of <tt>self</tt> indicating that a new usage should be
+      # switch to in the parent caluclation. This method has the effect of
+      # (de)activating terms in the parent calculation as appropriate.
+      #
+      def value(*args)
+        unless args.empty?
+          @value=args.first
+          activate_selected(value)
+        end
+        super
+      end
+
+      # Activate and deactivate terms in the parent calculation according to the
+      # compulsory/optional/forbidden status' of each in the usage indicated by
+      # <tt>usage</tt>
+      #
+      def activate_selected(usage=nil)
+        parent.profiles.in_use(usage).each do |term|
+          case @inactive
+          when :invisible
+            term.show!
+          when :disabled
+            term.enable!
+          end
+        end
+        parent.profiles.out_of_use(usage).each do |term|
+          case @inactive
+          when :invisible
+            term.hide!
+          when :disabled
+            term.disable!
+          end
+        end
+      end
+
+      # Returns an array of available valid values for <tt>self</tt>.
+      def choices
+        parent.amee_usages
+      end
+    end
+  end
+end

data/lib/config/amee_units.rb

@@ -0,0 +1,129 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+require 'quantify'
+
+Quantify::Unit.configure do
+
+  # Remove from the system of known units, the units which are not used or not
+  # anticipated to be useful for interacting with AMEE. These either represent
+  # physical quantities which are not typically represented in emissions
+  # calculations (e.g. redioactivity, thermal resistance) or units which do
+  # represent appropriate physical quantities but are relatively obscure or
+  # inappropriate (e.g angstrom, calorie, cup, light year).
+  #
+  # Note: although AMEE supports 8 types of British thermal unit, only one is
+  # made available since it is unlikely that users would like to choose between
+  # each of the alternatives.
+
+  required_units = [ "1",
+                     "Hz",
+                     "Ohm",
+                     "V",
+                     "m/s",
+                     "m/s²",
+                     "A",
+                     "K",
+                     "m",
+                     "mol",
+                     "s",
+                     "kg",
+                     "g",
+                     "km",
+                     "m³",
+                     "J",
+                     "N",
+                     "W",
+                     "Pa",
+                     "m²",
+                     "atm",
+                     "bar",
+                     "ha",
+                     "L",
+                     "bbl",
+                     "oz_fl_uk",
+                     "gal_uk",
+                     "gallon_dry_us",
+                     "oz_fl",
+                     "bbl_fl_us",
+                     "gal",
+                     "kWh",
+                     "°C",
+                     "°F",
+                     "°R",
+                     "ft",
+                     "h",
+                     "in",
+                     "mi",
+                     "min",
+                     "month",
+                     "nmi",
+                     "oz",
+                     "lb",
+                     "t",
+                     "week",
+                     "yd",
+                     "year",
+                     "BTU_FiftyNineF",
+                     "ton_us",
+                     "ton_uk",
+                     "d" ]
+
+  uneeded_units = []
+
+  units.each do |unit|
+    uneeded_units << unit.label unless required_units.include?(unit.label)
+  end
+
+  unload(uneeded_units)
+
+end
+
+Quantify::Unit::SI.configure do
+
+  # Load the commonly used SI unit/prefix combinations which are used in AMEE
+  prefix_and_load [:mega,:giga], :gram
+  prefix_and_load [:mega,:giga,:tera], :joule
+  prefix_and_load [:kilo,:mega], :watt
+
+end
+
+Quantify::Unit::Prefix::NonSI.configure do
+
+  # define the nonconventional 'M' (million) prefix which is used with British
+  # thermal units. This is similar, but distinct to the SI mega- prefix
+  load :name => 'million ', :symbol => 'M', :factor => 1e6
+
+end
+
+Quantify::Unit::NonSI.configure do
+
+  # Give the remaining (default) British thermal unit version a humanised name
+  # and symbol
+  Unit.BTU_FiftyNineF.configure_as_canonical do |unit|
+    unit.name = 'british thermal unit'
+    unit.symbol = 'BTU'
+  end
+
+  # Differentiate long and short ton symbols
+  Unit.ton_us.configure_as_canonical do |unit|
+    unit.symbol = 'ton (US)'
+  end
+
+  Unit.ton_uk.configure_as_canonical do |unit|
+    unit.symbol = 'ton (UK)'
+  end
+
+  # AMEE uses 'day' rather than 'd' as the label for the time period, day
+  Unit.day.canonical_label = 'day'
+
+  # Load prefixed version of British thermal unit, which is used in AMEE
+  prefix_and_load :M, :BTU_FiftyNineF
+
+  # Define and load the megawatt hour, an energy unit used in AMEE
+  construct_and_load(megawatt*hour) do |unit|
+    unit.symbol = 'MWh'
+    unit.label = 'MWh'
+  end
+  
+end

data/lib/core-extensions/class.rb

@@ -0,0 +1,27 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: Class
+
+class Class
+
+  # Syntactic sugar for providing instance level attributes. Similar to
+  # <tt>attr_accessor</tt> except the value of property is set without requiring
+  # "=" syntax, e.g.
+  # 
+  #   foo.propname 5        (rather than <tt>foo.attrname=5</tt>)
+  #
+  #   foo.propname            #=> 5
+  #
+  # In other words, setting is performed by specifing an argument, getting is
+  # performed using the same method call without an argument.
+  #
+  def attr_property(*accessors)
+    accessors.each do |m|
+      define_method(m) do |*val|
+        instance_variable_set("@#{m}",val.first) unless val.empty? #Array Hack to avoid warning
+        instance_variable_get("@#{m}")
+      end
+    end
+  end
+end

data/lib/core-extensions/hash.rb

@@ -0,0 +1,43 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: Hash
+
+class Hash
+
+  # Return a new instance of <i>Hash</i> which represents the same data as
+  # <tt>self</tt> but with all keys - including those of sub-hashes - symbolized
+  #
+  def recursive_symbolize_keys
+    new_hash = {}
+    self.each_pair do |k,v|
+      new_hash[k.to_sym] = value_or_symbolize_value(v)
+    end
+    new_hash
+  end
+
+  # Modify <tt>self</tt> in place, transforming all keys - including those of
+  # sub-hashes - in to symbols
+  #
+  def recursive_symbolize_keys!
+    self.each_pair do |k,v|
+      value = delete(k)
+      self[k.to_sym] = value_or_symbolize_value(value)
+    end
+    self
+  end
+
+  private
+
+  # Symbolize any hash key or sub-hash key containing within <tt>value</tt>.
+  def value_or_symbolize_value(value)
+    if value.is_a? Hash
+      return value.recursive_symbolize_keys
+    elsif value.is_a? Array
+      return value.map { |elem| value_or_symbolize_value(elem) }
+    else
+      return value
+    end
+  end
+
+end

data/lib/core-extensions/ordered_hash.rb

@@ -0,0 +1,21 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: OrderedHash
+
+module ActiveSupport
+  class OrderedHash
+
+    # Version of enumerable#select for an OrderedHash which is order-preserving
+    # Output is an array of key-value pairs.
+    def stable_select(&block)
+      #Annoyingly, default ordered hash select is not stable
+      self.map{|k,v| block.call(k,v) ? [k,v] : nil}.compact
+    end
+
+    # Insert a given element at the beginning, not end, of an ordered hash.
+    def insert_at_start(key,value)
+      replace(OrderedHash[self.to_a.insert(0,[key,value])])
+      end
+  end
+end