quantify 1.0.0

data/lib/quantify/dimensions.rb

@@ -0,0 +1,523 @@
+#! usr/bin/ruby
+
+module Quantify
+
+  # The Dimensions class represents specfic physical quantities in
+  # terms of powers of their constituent base dimensions, e.g.:
+  # 
+  # area = length^2
+  # force = mass^1 x length^1 x time^-2
+  # 
+  # Each dimension object is characterised by instance variables
+  # which describe the power (or index) of the respective base dimensions.
+  # Dimension objects can be manipulated - multiplied, divided, raised
+  # to powers, etc.
+  #
+  # Standard physical quantities (e.g. length, acceleration, energy)
+  # are loaded into the @@dimensions class variable at runtime. These
+  # can be accessed, used and manipulated for arbitrary dimensional uses.
+  # 
+  # Instances of Dimensions are also used as the basis for defining and
+  # manipulating objects of the Unit::Base class.
+
+  class Dimensions
+
+    # The BASE_QUANTITIES array specifies the system of base quantities
+    # upon which all Dimensions objects are defined.
+    #
+    # :information, :currency, :item represent tentative additions to
+    # the standard set of base quantities.
+    #
+    # :item is intended to represent arbitrary 'things' for specifying
+    # quantities such as, for example:
+    #
+    # 'dollars per capita' (:currency => 1, :items => -1)
+    # 'trees per hectare' (:items => 1, :length => -2).
+    #
+    BASE_QUANTITIES = [
+      :mass, :length, :time, :electric_current, :temperature,
+      :luminous_intensity, :amount_of_substance, :information,
+      :currency, :item ]
+
+    # Class variable which holds in memory all defined (and 'loaded') quantities
+    @@dimensions = []
+
+    # Provides access the class array which holds all defined quantities
+    def self.dimensions
+      @@dimensions
+    end
+
+    # Returns an array of Dimensions objects representing just the base quantities,
+    # i.e. length, mass, time, temperature, etc.
+    #
+    def self.base_dimensions
+      @@dimensions.select do |dimensions|
+        BASE_QUANTITIES.map(&:standardize).include? dimensions.describe
+      end
+    end
+
+    # This method allows specific, named quantities to be initialized and
+    # loaded into the @@dimensions array. Quantities are specified by their
+    # consituent base dimensions, but must also include a name/description,
+    # i.e. 'acceleration', :force - indicated by the :physical_quantity key -
+    # in order to be included in the system of known dimensions, e.g.:
+    #
+    #  Dimensions.load :physical_quantity => :force,
+    #                  :length => 1,
+    #                  :mass => 1,
+    #                  :time => -2
+    #
+    # Standard quantities such as force, energy, mass, etc. should not need to
+    # be defined as they are included in the set of quantities already defined
+    # (see config.rb) and automatically loaded. These can be removed, overridden
+    # or configured differently if desired.
+    #
+    def self.load(options)
+      if options[:physical_quantity]
+        @@dimensions << Dimensions.new(options)
+      else
+        raise InvalidDimensionError, "Cannot load dimensions without physical quantity description"
+      end
+    end
+
+    # Remove a dimension from the system of known dimensions
+    def self.unload(*unloaded_dimensions)
+      [unloaded_dimensions].flatten.each do |unloaded_dimension|
+        unloaded_dimension = Dimensions.for(unloaded_dimensions)
+        @@dimensions.delete_if { |unit| unit.physical_quantity == unloaded_dimension.physical_quantity }
+      end
+    end
+
+    # Returns an array containing the names/descriptions of all known (loaded)
+    # physical quantities, e.g.:
+    #
+    #  Dimensions.physical_quantities     #=>    [ 'acceleration',
+    #                                              'area',
+    #                                              'electric Current',
+    #                                               ... ]
+    #
+    def self.physical_quantities
+      @@dimensions.map(&:physical_quantity)
+    end
+
+    # Retrieve a known quantity - returns a Dimensions instance, which is a
+    # clone of the initialized instance of the specified quantity. This enables
+    # the object to be modified/manipulated without corrupting the representation
+    # of the quantity in the @@dimensions class array.
+    #
+    # The required quantity name/descriptor can be specified as a symbol or a
+    # string, e.g.:
+    # 
+    #  Dimensions.for :acceleration
+    #  Dimensions.for 'luminous_flux'
+    # 
+    # These can be shortened to, e.g. Dimensions.acceleration by virtue of the 
+    # #method_missing class method (below)
+    #
+    def self.for(name)
+      return name if name.is_a? Dimensions
+      if name.is_a? String or name.is_a? Symbol
+        if quantity = @@dimensions.find do |quantity|
+            quantity.physical_quantity == name.standardize.downcase
+          end
+          return quantity.clone
+        else
+          raise InvalidArgumentError, "Physical quantity not known: #{name}"
+        end
+      else
+        raise InvalidArgumentError, "Argument must be a Symbol or String"
+      end
+    end
+
+    # Syntactic sugar for defining the known quantities. This method simply
+    # evaluates code within the context of the Dimensions class, enabling
+    # the required quantities to be loaded at runtime, e.g.
+    #
+    #  Dimensions.configure do
+    #
+    #    load :physical_quantity => :length, :length => 1
+    #    load :physical_quantity => :area, :length => 2
+    #    load :physical_quantity => :power, :mass => 1, :length => 2, :time => -3
+    #
+    #  end
+    #
+    def self.configure &block
+        self.class_eval &block if block
+    end
+
+    # Provides a shorthand for retrieving known quantities, e.g.:
+    #
+    #  Dimensions.force
+    #
+    # is equivalent to
+    #
+    #  Dimensions.for :force
+    #
+    # Both variants return a clone of the initialized dimensional representation
+    # of the specified physical quantity (i.e. force).
+    #
+    def self.method_missing(method, *args, &block)
+      if dimensions = self.for(method)
+        return dimensions
+      end
+      super
+    end
+
+    BASE_QUANTITIES.each { |quantity| attr_reader quantity }
+
+    attr_accessor :physical_quantity
+
+    # Initialize a new Dimension object.
+    #
+    # The options argument is a hash which represents the base dimensions that
+    # define the physical quantity. Each key-value pair should consist of a key
+    # included in the BASE_QUANTITIES array, and a value which represents the
+    # index/power of that base quantity.
+    #
+    # In addition, a name or description of the physical quantity can be
+    # specified (i.e. 'acceleration', 'electric_current'). This is optional for
+    # creating a new Dimensions instance, but required if that object is to be
+    # loaded into the @@dimensions class array. e.g.:
+    #
+    #  Dimensions.new :physical_quantity => :density,
+    #                 :mass => 1,
+    #                 :length => -3
+    #
+    def initialize(options={})
+      if options.has_key?(:physical_quantity)
+        @physical_quantity = options.delete(:physical_quantity).standardize.downcase
+      end
+      enumerate_base_quantities(options)
+      describe
+    end
+
+    # Load an already instantiated Dimensions object into the @@dimensions class
+    # array, from which it will be accessible as a universal representation of
+    # that physical quantity.
+    #
+    # Object must include a non-nil @physical_quantity attribute, i.e. a name or
+    # description of the physical quantity represented.
+    #
+    def load
+      if describe and not loaded?
+        @@dimensions << self
+      elsif describe
+        raise InvalidDimensionError, "A dimension instance with the same physical quantity already exists"
+      else
+        raise InvalidDimensionError, "Cannot load dimensions without physical quantity description"
+      end
+    end
+
+    def loaded?
+      Dimensions.dimensions.any? { |quantity| self.has_same_identity_as? quantity }
+    end
+
+    # Remove from system of known units.
+    def unload
+      Dimensions.unload(self.physical_quantity)
+    end
+
+    def has_same_identity_as?(other)
+      self.physical_quantity == other.physical_quantity and not self.physical_quantity.nil?
+    end
+
+    # Return a description of what physical quantity self represents. If no
+    # value is found in the @physical_quantity instance variable, the task is
+    # delegated to the #get_description method.
+    #
+    def describe
+      @physical_quantity or get_description
+    end
+
+    # Searches the system of known physical quantities (@@dimensions class
+    # array) looking for any which match self in terms of the configuration of
+    # base dimensions, i.e. an object which dimensionally represents the same
+    # thing.
+    #
+    # If found, the name/description of that quantity is assigned to the
+    # @physical_quantity attribute of self.
+    #
+    # This method is useful in cases where Dimensions instances are manipulated
+    # using operators (e.g. multiply, divide, power, reciprocal), resulting in
+    # a change to the configuration of base dimensions (perhaps as a new instance).
+    # This method tries to find a description of the new quantity.
+    #
+    # If none is found, self.physical_quantity is set to nil.
+    #
+    def get_description
+      similar = @@dimensions.find { |quantity| quantity == self }
+      @physical_quantity = ( similar.nil? ? nil : similar.physical_quantity )
+    end
+
+    # Returns an array containing the known units which represent the physical
+    # quantity described by self
+    #
+    # If no argument is given, the array holds instances of Unit::Base (or
+    # subclasses) which represent each unit. Alternatively only the names or
+    # symbols of each unit can be returned by providing the appropriate unit
+    # attribute as a symbolized argument, e.g.
+    #
+    #   Dimensions.energy.units             #=> [ #<Quantify::Dimensions: .. >,
+    #                                             #<Quantify::Dimensions: .. >,
+    #                                             ... ]
+    #
+    #   Dimensions.mass.units :name         #=> [ 'kilogram', 'ounce',
+    #                                             'pound', ... ]
+    #
+    #   Dimensions.length.units :symbol     #=> [ 'm', 'ft', 'yd', ... ]
+    #
+    def units(by=nil)
+      Unit.units.select { |unit| unit.dimensions == self }.map(&by)
+    end
+
+    # Returns the SI unit for the physical quantity described by self.
+    #
+    # Plane/solid angle are special cases which are dimensionless units, and so
+    # are handled explicitly. Otherwise, the si base units for each of the base
+    # dimensions of self are indentified and the corresponding compound unit is
+    # derived. If this new unit is the same as a known (SI derived) unit, the
+    # known unit is returned.
+    #
+    #   Dimensions.energy.units                  #=> #<Quantify::Dimensions: .. >
+    #
+    #   Dimensions.energy.si_unit.name           #=> 'joule'
+    #
+    #   Dimensions.kinematic_viscosity.si_unit.name
+    #
+    #                                            #=> 'metre squared per second'
+    #
+    def si_unit
+      return Unit.steridian if self.describe == 'solid angle'
+      return Unit.radian if self.describe == 'plane angle' 
+      return si_base_units.inject(Unit.unity) do |compound,unit|
+        compound * unit
+      end.or_equivalent
+    rescue
+      return nil
+    end
+
+    # Returns an array representing the base SI units for the physical quantity
+    # described by self
+    #
+    # If no argument is given, the array holds instances of Unit::Base (or
+    # subclasses) which represent each base unit. Alternatively only the names
+    # or symbols of each unit can be returned by providing the appropriate unit
+    # attribute as a symbolized argument, e.g.
+    #
+    #   Dimensions.energy.si_base_units       #=> [ #<Quantify::Unit: .. >,
+    #                                               #<Quantify::Unit: .. >,
+    #                                               ... ]
+    #
+    #   Dimensions.energy.si_base_units :name
+    #
+    #                                         #=> [ "metre squared",
+    #                                               "per second squared",
+    #                                               "kilogram"]    #
+    #
+    #   Dimensions.force.units :symbol        #=> [ "m", "s^-2", "kg"]
+    #
+    def si_base_units(by=nil)
+      self.to_hash.map do |dimension,index|
+        Unit.si_base_units.select do |unit|
+          unit.measures == dimension.standardize
+        end.first.clone ** index
+      end.map(&by)
+    end
+
+    # Compares the base quantities of two Dimensions objects and returns true if
+    # they are the same. This indicates that the two objects represent the same
+    # physical quantity (irrespective of their names - @physical_quantity - being
+    # similar, different, or absent.
+    #
+    def ==(other)
+      self.to_hash == other.to_hash
+    end
+
+    # Returns true if the physical quantity that self represents is known
+    def is_known?
+      describe ? true : false
+    end
+
+    # Returns true if self is a dimensionless quantity
+    def is_dimensionless?
+      base_quantities.empty?
+    end
+
+    # Returns true if self represents one of the base quantities (i.e. length,
+    # mass, time, etc.)
+    def is_base?
+      base_quantities.size == 1 and
+        self.instance_variable_get(base_quantities.first) == 1 ? true : false
+    end
+
+    # Method for identifying quantities which are 'specific' quantities, i.e
+    # quantities which represent a quantity of something *per unit mass*
+    #
+    def is_specific_quantity?
+      denominator_quantities == ["@mass"]
+    end
+
+    # Method for identifying quantities which are 'molar' quantities, i.e
+    # quantities which represent a quantity of something *per mole*
+    #
+    def is_molar_quantity?
+      denominator_quantities == ["@amount_of_substance"]
+    end
+
+
+    # Multiplies self by another Dimensions object, returning self with an
+    # updated configuration of dimensions. Since this is likely to have resulted
+    # in the representation of a different physical quantity than was originally
+    # represented, the #get_description method is invoked to attempt to find a
+    # suitable description.
+    #
+    def multiply!(other)
+      enumerate_base_quantities(other.to_hash)
+      get_description
+      return self
+    end
+
+    # Similar to #multiply! but returns a new Dimensions instance representing
+    # the physical quantity which results from the multiplication.
+    #
+    def multiply(other)
+      Dimensions.new(self.to_hash).multiply! other
+    end
+
+    # Similar to #multiply! but performs a division of self by the specified
+    # Dimensions object.
+    #
+    def divide!(other)
+      enumerate_base_quantities(other.reciprocalize.to_hash)
+      get_description
+      return self
+    end
+
+    # Similar to #divide! but returns a new Dimensions instance representing
+    # the physical quantity which results from the division.
+    #
+    def divide(other)
+      Dimensions.new(self.to_hash).divide! other
+    end
+
+    # Raises self to the power provided. As with multiply and divide, the
+    # #get_description method is invoked to attempt to find a suitable
+    # description for the new quantity represented.
+    #
+    def pow!(power)
+      make_dimensionless if power == 0
+      if power < 0
+        self.reciprocalize!
+        power *= -1
+      end
+      original_dimensions = self.clone
+      (power - 1).times { self.multiply!(original_dimensions) }
+      get_description
+      return self
+    end
+
+    # Similar to #pow! but returns a new Dimensions instance representing
+    # the physical quantity which results from the raised power.
+    #
+    def pow(power)
+      Dimensions.new(self.to_hash).pow!(power)
+    end
+
+    # Inverts self, returning a representation of 1/self. This is equivalent to
+    # raising to the power -1. The #get_description method is invoked to attempt
+    # to find a suitable description for the new quantity represented.
+    #
+    def reciprocalize!
+      base_quantities.each do |variable|
+        new_value = self.instance_variable_get(variable) * -1
+        self.instance_variable_set(variable, new_value)
+      end
+      get_description
+      return self
+    end
+
+    # Similar to #reciprocalize! but returns a new Dimensions instance representing
+    # the physical quantity which results from the inversion.
+    #
+    def reciprocalize
+      Dimensions.new(self.to_hash).reciprocalize!
+    end
+
+    alias :times :multiply
+    alias :* :multiply
+    alias :/ :divide
+    alias :** :pow
+
+    protected
+
+    # Returns an array containing the names of the instance variables which
+    # represent the base quantities of self. This enables various operations to
+    # be performed on these variables without touching the @physical_quantity
+    # variable.
+    #
+    def base_quantities
+      quantities = self.instance_variables
+      quantities.delete("@physical_quantity")
+      return quantities
+    end
+
+    # Just the base quantities which have positive indices
+    def numerator_quantities
+      base_quantities.select { |quantity| self.instance_variable_get(quantity) > 0 }
+    end
+
+    # Just the base quantities which have negative indices
+    def denominator_quantities
+      base_quantities.select { |quantity| self.instance_variable_get(quantity) < 0 }
+    end
+
+    # Returns a hash representation of the base dimensions of self. This is used
+    # in various operations and is useful for instantiating new objects with
+    # the same base dimensions.
+    #
+    def to_hash
+      hash = {}
+      base_quantities.each do |variable|
+        hash[variable.gsub("@","").to_sym] = self.instance_variable_get(variable)
+      end
+      return hash
+    end
+
+    # Method for initializing the base quantities of self.
+    #
+    # Where base quantities are already defined, the new indices are added to
+    # the existing ones. This represents the multiplication of base quantities
+    # (multiplication of similar quantities involves the addition of their
+    # powers).
+    #
+    # This method is therefore used in the multiplication of Dimensions objects,
+    # but also in divisions and raising of powers following other operations.
+    #
+    def enumerate_base_quantities(options)
+      options.each_pair do |base_quantity,index|
+        base_quantity = base_quantity.to_s.downcase.to_sym
+        unless index.is_a? Integer and BASE_QUANTITIES.include? base_quantity
+          raise InvalidDimensionError, "An invalid base quantity was specified (#{base_quantity})"
+        end
+        variable = "@#{base_quantity}"
+        if self.instance_variable_defined?(variable)
+          new_index = self.instance_variable_get(variable) + index
+          if new_index == 0
+            remove_instance_variable(variable)
+          else
+            self.instance_variable_set(variable, new_index)
+          end
+        else
+          self.instance_variable_set(variable, index)
+        end
+      end
+    end
+
+    # Make object represent a dimensionless quantity.
+    def make_dimensionless
+      self.physical_quantity = 'dimensionless'
+      base_quantities.each { |var| remove_instance_variable(var) }
+    end
+
+  end
+end

data/lib/quantify/exception.rb

@@ -0,0 +1,21 @@
+module Quantify
+
+  class QuantityParseError < Exception
+  end
+
+  class InvalidObjectError < Exception
+  end
+
+  class InvalidUnitError < Exception
+  end
+
+  class InvalidDimensionError < Exception
+  end
+
+  class InvalidPhysicalQuantityError < Exception
+  end
+
+  class InvalidArgumentError < Exception
+  end
+
+end

data/lib/quantify/inflections.rb

@@ -0,0 +1,63 @@
+
+ActiveSupport::Inflector.inflections do |inflect|
+
+  inflect.uncountable %w( clo hertz lux siemens )
+
+  inflect.plural /(metre)/i, '\1s'
+  inflect.singular /(metre)s?/i, '\1'
+
+  inflect.plural /(degree)/i, '\1s'
+  inflect.singular /(degree)s?/i, '\1'
+
+  inflect.plural /(barrel)/i, '\1s'
+  inflect.singular /(barrel)s?/i, '\1'
+
+  inflect.plural /(unit)/i, '\1s'
+  inflect.singular /(unit)s?/i, '\1'
+
+  inflect.plural /(ounce)/i, '\1s'
+  inflect.singular /(ounce)s?/i, '\1'
+
+  inflect.plural /(volt)/i, '\1s'
+  inflect.singular /(volt)s?/i, '\1'
+
+  inflect.plural /(foot)/i, 'feet'
+  inflect.singular /(feet)/i, 'foot'
+
+  inflect.plural /(gallon)/i, '\1s'
+  inflect.singular /(gallon)s?/i, '\1'
+
+  inflect.plural /(horsepower)/i, '\1'
+  inflect.singular /(horsepower)/i, '\1'
+
+  inflect.plural /(hundredweight)/i, '\1'
+  inflect.singular /(hundredweight)/i, '\1'
+
+  inflect.plural /(inch)/i, '\1es'
+  inflect.singular /(inch)(es)?/i, '\1'
+
+  inflect.plural /(league)/i, '\1s'
+  inflect.singular /(league)s?/i, '\1'
+
+  inflect.plural /(mass)/i, '\1es'
+  inflect.singular /(mass)(es)?/i, '\1'
+
+  inflect.plural /(mile)/i, '\1s'
+  inflect.singular /(mile)s?/i, '\1'
+
+  inflect.plural /(pound)/i, '\1s'
+  inflect.singular /(pound)s?/i, '\1'
+
+  inflect.plural /(ton)/i, '\1s'
+  inflect.singular /(ton)s?/i, '\1'
+
+  inflect.plural /(tonne)/i, '\1s'
+  inflect.singular /(tonne)s?/i, '\1'
+
+  inflect.plural /(stone)/i, '\1s'
+  inflect.singular /(stone)s?/i, '\1'
+
+  inflect.irregular 'footcandle', 'footcandles'
+  inflect.irregular 'kilowatt hour', 'kilowatt hours'
+
+end

data/lib/quantify/quantify.rb

@@ -0,0 +1,37 @@
+module Quantify
+
+  def self.configure &block
+    self.module_eval &block if block
+  end
+
+  module ExtendedMethods
+
+    # Provides syntactic sugar for accessing units via the #for method.
+    # Specify:
+    #
+    #  Unit.degree_celsius
+    #
+    # rather than Unit.for :degree_celsius
+    #
+    def method_missing(method, *args, &block)
+      if method.to_s =~ /((si|non_si|compound)_)?(non_(prefixed)_)?((base|derived|benchmark)_)?units(_by_(name|symbol|label))?/
+        if $2 or $4 or $6
+          conditions = []
+          conditions << "unit.is_#{$2}_unit?" if $2
+          conditions << "!unit.is_prefixed_unit?" if $4
+          conditions << "unit.is_#{$6}_unit?" if $6
+          units = Unit.units.select { |unit| instance_eval(conditions.join(" and ")) }
+        else
+          units = Unit.units
+        end
+        return_format = ( $8 ? $8.to_sym : nil )
+        units.map(&return_format)
+      elsif unit = Unit.for(method)
+        return unit
+      else
+        super
+      end
+    end
+    
+  end
+end