sy 2.0.2 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c1ff970013f49cfd8677a9dad33067247e8a2df5
-  data.tar.gz: 6f3c4c65c65f0a90994a699703474ba9d73a9c73
+  metadata.gz: fd4b854cf2fceae1fb55d2e657f219807f88f6c6
+  data.tar.gz: 730fec5dad579f42e482d49cbaad66b56e901685
 SHA512:
-  metadata.gz: 513505ef33494723ffb05ab0aa0d8aa9bddd9a4663d15aceecb74bd96a3a5530f81c150e30ff0f3874ffed8dc8f5e4a4536d75db8bc629d85becd042332a1298
-  data.tar.gz: 1e5cab9de6e72cdde63d6b4e43a71d1dfa4fb6a1ba49380695ac10fdc6d6de83d8b00255386e9cee2250c9587382dfaac69a4cddab5e37d29d714e7acdbb8d77
+  metadata.gz: 2b2c9f2994e1d30db45eeeed40f952aad46e619a3935db909b2446f2b08f169525216cca37f49747abaf3dbc30213f38da505dd3e0ef0d4e84e678bf00d67807
+  data.tar.gz: ca82955c039d47f775292f3b1ee9c92ef6cba91ea0b0b99af4ae4f2666f90b0f9366b267b8e98299d195d94902d82dcb50f68fb632a6e32a3fb9fe4d0f314030

data/lib/sy.rb

@@ -14,7 +14,7 @@ require 'active_support/core_ext/string/starts_ends_with'
 require_relative 'sy/version'
 require_relative 'sy/expressible_in_units'
 require_relative 'sy/fixed_assets_of_the_module'
-require_relative 'sy/mapping'
+require_relative 'sy/measure'
 require_relative 'sy/dimension'
 require_relative 'sy/quantity'
 require_relative 'sy/composition'
@@ -141,8 +141,12 @@ module SY
   CelsiusTemperature = Quantity.of :Θ
 
   # Degree celsius is SY::CELSIUS
-  CELSIUS = Unit.standard of: CelsiusTemperature, short: '°C'
-  # FIXME: Patch CelsiusTemperature to make it work with SY::Temperature
+  CELSIUS = Unit.standard of: CelsiusTemperature, short: '°C', measure: SY::Measure.simple_offset( TRIPLE_POINT_OF_WATER.in( :K ) )
+
+  class << CelsiusTemperature
+    # FIXME: Patch CelsiusTemperature to make it work with SY::Temperature
+  end
+
   # alias :°C :celsius                 # with U+00B0 DEGREE SIGN
   # alias :˚C :celsius                 # with U+02DA RING ABOVE
   # alias :℃ :celsius                  # U+2103 DEGREE CELSIUS
@@ -258,7 +262,7 @@ module SY
   VOLT = Unit.standard of: ElectricPotential, short: "V"
 
   # FIXME: This should raise a friendly error:
-  # MOLAR = Unit.standard of: Molarity, abbreviation: "M", amount: 1.mol.l⁻¹
+  # MOLAR = Unit.standard of: Molarity, short: "M", amount: 1.mol.l⁻¹
 
   # SY::Molality...
   Molality = MoleAmount / Mass

data/lib/sy/absolute_magnitude.rb

@@ -1,26 +1,25 @@
-#encoding: utf-8
-
+# -*- coding: utf-8 -*-
 # Qualities specific to absolute magnitudes.
 # 
 module SY::AbsoluteMagnitude
   # Absolute magnitude constructor takes :quantity (alias :of) named argument,
   # and :amount named argument, where amount must be nonnegative.
   # 
-  def initialize args={}
-    @quantity = args[:quantity] || args[:of]
-    amnt = args[:amount]
-    @amount = case amnt
-              when Numeric then amnt
+  def initialize( of: ( fail ArgumentError, ":of argument missing!" ),
+                  amount: nil )
+    @quantity = of
+    @amount = case amount
+              when Numeric then amount
               when nil then 1
               else
                 begin
-                  amnt.amount
+                  amount.amount
                 rescue NameError, NoMethodError
-                  amnt
+                  amount
                 end
               end
-    raise SY::MagnitudeError,
-          "Unsigned magnitudes canot have negative amount!" if @amount < 0
+    fail SY::MagnitudeError, "Unsigned magnitudes may not have negative " +
+      "amount!" if @amount < 0
   end
 
   # For absolute magnitudes, #+ method always returns a result framed in

data/lib/sy/composition.rb

@@ -1,5 +1,4 @@
-#encoding: utf-8
-
+# -*- coding: utf-8 -*-
 # Composition of quantities.
 # 
 class SY::Composition < Hash
@@ -11,6 +10,7 @@ class SY::Composition < Hash
   SR << -> ꜧ {
     ꜧ.reject! { |qnt, _| qnt == SY::Amount || qnt == SY::Amount.relative }
   }
+
   # Relative quantities of the composition are absolutized:
   SR << -> ꜧ {
     ꜧ.select { |qnt, _| qnt.relative? }.each { |qnt, exp|
@@ -18,10 +18,14 @@ class SY::Composition < Hash
       ꜧ.update qnt.absolute => exp
     }
   }
+
   # Any quantities with exponent zero can be deleted:
   SR << -> ꜧ {
     ꜧ.reject! { |_, exp| exp == 0 }
   }
+
+  # TODO: This undocumented simplification rule simplifies MoleAmount and
+  # LitreVolume into Molarity.
   # 
   SR << -> ꜧ {
     begin
@@ -103,6 +107,8 @@ class SY::Composition < Hash
   # is a base dimension.
   # 
   def atomic?
+    puts "composition is #{self}" if SY::DEBUG
+    puts "first[0].dimension is #{first[0].dimension}" if SY::DEBUG
     singular? && first[0].dimension.base?
   end
 
@@ -170,21 +176,28 @@ class SY::Composition < Hash
     SY::Quantity.new args.merge( composition: self )
   end
 
-  # Dimension of a quantity composition is the sum of its dimensions.
+  # Dimension of a composition is the sum of its member quantities' dimensions.
   # 
   def dimension
     map { |qnt, exp| qnt.dimension * exp }.reduce SY::Dimension.zero, :+
   end
 
-  # Infers the mapping of the composition's quantity. (Mapping
-  # defines mapping of a quantity to the standard quantity of its dimension.)
+  # Infers the measure of the composition's quantity. ('Measure' means measure
+  # of the pertinent standard quantity.)
   # 
-  def infer_mapping
-    puts "#infer_mapping; hash is #{self}" if SY::DEBUG
+  def infer_measure
+    puts "#infer_measure; hash is #{self}" if SY::DEBUG
     map do |qnt, exp|
-      qnt.standardish? ? SY::Mapping.identity :
-        qnt.mapping_to( qnt.standard ) ** exp
-    end.reduce( SY::Mapping.identity, :* )
+      puts "#infer_measure: doing quantity #{qnt} with exponent #{exp}!" if SY::DEBUG
+      if qnt.standardish? then
+        puts "#{qnt} standardish" if SY::DEBUG
+        SY::Measure.identity
+      else
+        puts "#{qnt} not standardish" if SY::DEBUG
+        puts "its measure is #{qnt.measure}, class #{qnt.measure.class}" if SY::DEBUG
+        qnt.measure( of: qnt.standard ) ** exp
+      end
+    end.reduce( SY::Measure.identity, :* )
   end
 
   # Simple composition is one that is either empty or singular.

data/lib/sy/dimension.rb

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 # This class represents physical dimension of a metrological quantity.
 # 
 class SY::Dimension

data/lib/sy/expressible_in_units.rb

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 # This mixin provides ability to respond to SY unit symbol methods.
 # 
 module SY::ExpressibleInUnits

data/lib/sy/fixed_assets_of_the_module.rb

@@ -1,5 +1,4 @@
 # -*- coding: utf-8 -*-
-
 # Here, fixed assets of the main module are set up.
 # 
 module SY

data/lib/sy/imperial.rb

@@ -18,6 +18,8 @@ module SY
 
   # === Volume
   PINT = Unit.of Volume, amount: 568.26125.cm³
+  # FIXME: PINT = Unit.of Volume, amount: 568.26125.ml didn't work, it gave 1000 times more value
+  # something is wrong with the conversion mechanics
   QUART = Unit.of Volume, amount: 2.pint
   GALLON = Unit.of Volume, short: 'gal', amount: 8.pint
 

data/lib/sy/magnitude.rb

@@ -1,22 +1,21 @@
-#encoding: utf-8
-
-# In physics, difference between absolute and relative magnitudes is well
-# understood. The magnitude class here represents absolute magnitude – physical
-# number of unit objects making up the amount of some metrological quantity.
-# Amounts of absolute magnitudes may not be negative. When one desires to
-# represent <em>difference</me> between magnitudes, which can be positive as
-# well as negative, relative magnitude has to be used.
+# -*- coding: utf-8 -*-
+# This class here represents absolute magnitude – physical number of unit
+# objects, that make up the amount of some metrological quantity. Amount of
+# an absolute magnitudes may not be negative – physical amounts cannot have
+# negative number of unit objects. But as for the <em>difference</me> between
+# magnitudes, this can be positive as well as negative – relative magnitudes
+# are used for this purpose.
 #
 # While ordinary #+ and #- methods of absolute magnitudes return relative
-# relative magnitudes, absolute magnitudes have additional methods #add and
-# #subtract, which return absolute magnitudes (it is the responsibility of the
-# caller to avoid negative results). Furthermore, absolute magnitudes have
-# special subtraction method #take, which guards against subtracting more than
-# the magnitude's amount.
+# magnitudes, absolute magnitudes have additional methods #add and #subtract,
+# that return absolute magnitudes (it is the responsibility of the caller to
+# avoid negative results). Furthermore, absolute magnitudes have one more
+# special method #take, which perfoms #subtract whilst protecting against
+# subtraction of more than, there is to take.
 # 
 module SY::Magnitude
   class << self
-    # Constructor of absolute magnitudes of a given quantity.
+    # Constructs absolute magnitudes of a given quantity.
     # 
     def absolute *args
       ꜧ = args.extract_options!
@@ -24,7 +23,7 @@ module SY::Magnitude
       return qnt.absolute.magnitude ꜧ[:amount]
     end
 
-    # Constructor of relative magnitudes of a given quantity.
+    # Constructs relative magnitudes of a given quantity.
     # 
     def difference *args
       ꜧ = args.extract_options!
@@ -32,13 +31,13 @@ module SY::Magnitude
       return qnt.relative.magnitude ꜧ[:amount]
     end
 
-    # Constructor of magnitudes of a given quantity.
+    # Constructs magnitudes of a given quantity.
     # 
     def of qnt, args={}
       return qnt.magnitude args[:amount]
     end
 
-    # Constructor of zero magnitude of a given quantity.
+    # Returns zero magnitude of a given quantity.
     # 
     def zero
       return absolute 0
@@ -204,8 +203,8 @@ module SY::Magnitude
   # 
   def reframe q2
     case q2
-    when SY::Quantity then q2.import self
-    when SY::Unit then q2.quantity.import self
+    when SY::Quantity then q2.read self
+    when SY::Unit then q2.quantity.read self
     else raise TypeError, "Unable to reframe into a #{q2.class}!" end
   end
 
@@ -215,8 +214,8 @@ module SY::Magnitude
   # 
   def call q2
     case q2
-    when SY::Quantity then q2.relative.import self
-    when SY::Unit then q2.quantity.relative.import self
+    when SY::Quantity then q2.relative.read self
+    when SY::Unit then q2.quantity.relative.read self
     else raise TypeError, "Unable to reframe into a #{q2.class}!" end
   end
 
@@ -392,6 +391,7 @@ module SY::Magnitude
       end
       
     rescue
+      fail
       number_ς = number_format % amount
       [ number_ς, "unit[#{quantity}]" ].join '.'
     end

data/lib/sy/mapping.rb

@@ -1,79 +1,132 @@
-#encoding: utf-8
-
-# Represents relationship of two quantities. Provides import and export
-# conversion closures. Instances are immutable and have 2 attributes:
+# -*- coding: utf-8 -*-
+# Represents a certain way, that a quantity <em>measures</em> another quantity
+# (reference quantity). Instance has two attributes:
 #
-# * im - import closure, converting amount of quantity 1 into quantity 2
-# * ex - export closure, converting amount of quantity 2 into quantity 1
+# * @r - read closure, for converting from the measured reference quantity.
+# * @w - write closure, for converting back to the reference quantity.
 #
-# Convenience methods for mapping magnitudes are:
-# 
-# * import - like im, but operates on magnitudes
-# * export - like ex, but operates on magnitudes
+# Convenience methods #read and #write facilitate their use.
 # 
-class SY::Mapping
+class SY::Measure
   class << self
+    # Identity measure.
+    # 
     def identity
-      new 1
+      simple_scale 1
+    end
+
+    # Simple scaling measure. (Eg. pounds vs kilograms)
+    # 
+    def simple_scale scale
+      new( ratio: scale )
+    end
+
+    # Simple offset measure. (Such as °C)
+    # 
+    def simple_offset offset
+      new( r: lambda { |ref_amnt| ref_amnt - offset },
+           w: lambda { |amnt| amnt + offset } )
+    end
+
+    # Linear (scaled offset) measure. Expects a hash with 2 points demonstrating
+    # the relationship: { ref_amount_1 => amount_1, ref_amount_2 => amount_2 }.
+    # (Example: Fahrenheit degrees vs. Kelvins.)
+    # 
+    def linear hsh
+      ref_amnt_1, amnt_1, ref_amnt_2, amnt_2 = hsh.to_a.flatten
+      scale = ( ref_amnt_2 - ref_amnt_1 ) / ( amnt_2 - amnt_1 )
+      new( r: lambda { |ref_amnt| amnt_1 + ( ref_amnt - ref_amnt_1 ) / scale },
+           w: lambda { |amnt| ref_amnt_1 + ( amnt - amnt_1 ) * scale } )
+    end
+
+    # Logarithmic.
+    # 
+    def logarithmic base=Math::E
+      new( r: lambda { |ref_amnt| Math.log ref_amnt, base },
+           w: lambda { |amnt| base ** amnt } )
+    end
+
+    # Negative logarithmic.
+    # 
+    def negative_logarithmic base=Math::E
+      new( r: lambda { |ref_amnt| -Math.log( ref_amnt, base ) },
+           w: lambda { |amnt| base ** ( -amnt ) } )
     end
   end
 
-  attr_reader :ex, :im, :ratio
+  attr_reader :r, :w, :ratio
 
-  # Takes either a magnitude (1 argument), or 2 named arguments :im, :ex
-  # speficying amount import and export closure. For a magnitude, these
-  # closures are constructed automatically, assuming simple ratio rule.
+  # The constructor expects :r and :w arguments for read and write closure.
   # 
-  def initialize arg
-    case arg
-    when Hash then
-      @ex, @im = arg[:ex], arg[:im]
+  def initialize ratio: nil,
+    r: ( fail ArgumentError, ":r closure not specified!" unless ratio ),
+    w: ( fail ArgumentError, ":w closure not specified!" unless ratio )
+    if ratio.nil?
+      fail TypeError, ":r and :w arguments must both be closures!" unless
+        r.is_a?( Proc ) && w.is_a?( Proc )
+      @ratio, @r, @w = nil, r, w
     else
-      @ratio = r = arg
-      @ex = lambda { |amount1| amount1 * r }
-      @im = lambda { |amount2| amount2 / r }
+      fail ArgumentError, ":r or :w must not be given if :ratio given!" if r || w
+      @ratio = ratio
+      @r = lambda { |ref_amnt| ref_amnt / ratio }
+      @w = lambda { |amnt| amnt * ratio }
     end
   end
 
-  def import magnitude, from_quantity
-    from_quantity.magnitude @im.( magnitude.amount )
+  # Convenience method to read a magnitude of a reference quantity.
+  # 
+  def read magnitude_of_reference_quantity, quantity
+    quantity.magnitude r.( magnitude_of_reference_quantity.amount )
   end
 
-  def export magnitude, to_quantity
-    to_quantity.magnitude @ex.( magnitude.amount )
+  # Convenience method to convert a magnitude back to the reference quantity.
+  # 
+  def write magnitude, reference_quantity
+    reference_quantity.magnitude w.( magnitude.amount )
   end
 
+  # Inverse measure.
+  # 
   def inverse
-    self.class.new begin
-                     1 / @ratio
-                   rescue NoMethodError, TypeError
-                     i, e = im, ex
-                     { im: e, ex: i } # swap closures
-                   end
+    if ratio.nil? then
+      self.class.new( r: w, w: r ) # swap closures
+    else
+      self.class.new( ratio: 1 / ratio )
+    end
   end
 
-  def * r2 # mapping composition
-    ç.new begin
-            @ratio * r2.ratio
-          rescue NoMethodError, TypeError
-            i1, i2, e1, e2 = im, r2.im, ex, r2.ex
-            { ex: lambda { |a1| e2.( e1.( a1 ) ) }, # export compose
-        im: lambda { |a2| i1.( i2.( a2 ) ) } } # import compose
-          end
+  # Measure composition (like f * g function composition).
+  # 
+  def * other
+    if ratio.nil? then
+      r1, r2, w1, w2 = r, other.r, w, other.w
+      self.class.new( r: lambda { |ref_amnt| r1.( r2.( ref_amnt ) ) },
+                      w: lambda { |amnt| w2.( w1.( amnt ) ) } )
+    else
+      self.class.new( ratio: ratio * other.ratio )
+    end
   end
 
-  def / r2
-    self * r2.inverse
+  # Measure composition with inverse of another measure.
+  # 
+  def / other
+    self * other.inverse
   end
 
+  # Measure power.
+  # 
   def ** n
-    ç.new begin
-            n == 1 ? @ratio * 1 : @ratio ** n
-          rescue NoMethodError, TypeError
-            i, e = im, ex
-            { ex: lambda { |a1| n.times.reduce a1 do |m, _| e.( m ) end },
-        im: lambda { |a2| n.times.reduce a2 do |m, _| i.( m ) end } }
-          end
+    if ratio.nil? then
+      r_closure, w_closure = r, w
+      self.class.new( r: lambda { |ref_amnt|
+                        n.times.inject ref_amnt do |m, _| r_closure.( m ) end
+                      },
+                      w: lambda { |amnt|
+                        n.times.inject amnt do |m, _| w_closure.( m ) end
+                      } )
+    else
+      self.class.new( ratio: ratio ** n )
+    end
   end
 
   protected