sy 1.0.0

data/lib/sy/expressible_in_units.rb

@@ -0,0 +1,135 @@
+#encoding: utf-8
+
+# This mixin endows a class with the capacity to respond to method
+# symbols corresponding to metrological units defined in SY.
+# 
+module SY::ExpressibleInUnits
+  class RecursionError < StandardError; end
+
+  def method_missing ß, *args, &block
+    # hack #0: working around a bug in a 3rd party library
+    return self if ß.to_s.include?( 'begin' ) || ß.to_s.include?( 'end' )
+    # hack #1: get rid of missing methods 'to_something', esp. #to_ary
+    super if ß == :to_ary || ß.to_s.starts_with?( 'to_' )
+    begin # prevent recurrent method_missing for the same symbol
+      anti_recursion_exec_with_token ß, :@SY_Units_mmiss do
+        puts "Method missing: '#{ß}'" if SY::DEBUG
+        # Parse the unit symbol.
+        prefixes, units, exps = parse_unit_symbol( ß )
+        # Define the unit method.
+        self.class.module_eval write_unit_method( ß, prefixes, units, exps )
+      end
+    rescue NameError => m
+      puts "NameError raised: #{m}" if SY::DEBUG
+      super # give up
+    rescue SY::ExpressibleInUnits::RecursionError
+      super # give up
+    else # invoke the defined method that we just defined
+      send ß, *args, &block
+    end
+  end
+
+  def respond_to_missing? ß, *args, &block
+    str = ß.to_s
+    return false if str.start_with?( 'to_' ) ||    # speedup hack
+      str == 'begin' || str == 'end' # bugs in 3rd party library
+    begin
+      anti_recursion_exec_with_token ß, :@SY_Units_rmiss do
+        parse_unit_symbol( ß )
+      end
+    rescue NameError, SY::ExpressibleInUnits::RecursionError
+      false
+    else
+      true
+    end
+  end
+
+  private
+
+  # Looking at the method symbol, delivered to #method_missing, this method
+  # figures out which SY units it represents, along with prefixes and exponents. 
+  # 
+  def parse_unit_symbol ß
+    SY::Unit.parse_sps_using_all_prefixes( ß ) # rely on SY::Unit
+  end
+
+  # Taking method name symbol as the first argument, and three more arguments
+  # representing equal-length arrays of prefixes, unit symbols and exponents,
+  # appropriate method string is written.
+  # 
+  def write_unit_method ß, prefixes, units, exponents
+    known_units = SY::Unit.instances
+    # A procedure to find unit based on name or abbreviation:
+    find_unit = lambda do |ς|
+      known_units.find { |u| u.name.to_s == ς || u.short.to_s == ς }
+    end
+    # Return prefix method or empty ς if not necessary.
+    prefix_method_ς = lambda do |prefix|
+      puts "About to call PREFIX TABLE.to_full with #{prefix}" if SY::DEBUG
+      full_prefix = SY::PREFIX_TABLE.to_full( prefix )
+      full_prefix == '' ? '' : ".#{full_prefix}"
+    end
+    # Return exponentiation string (suffix) or empty ς if not necessary.
+    exponentiation_ς = lambda do |exponent|
+      exponent == 1 ? '' : " ** #{exponent}"
+    end
+    # Prepare prefix / unit / exponent triples for making factor strings:
+    triples = [ prefixes, units, exponents ].transpose
+    # A procedure for triple processing before use:
+    process_triple = lambda do |prefix, unit_ς, exponent|
+      [ find_unit.( unit_ς ).name.to_s.upcase,
+        prefix_method_ς.( prefix ),
+        exponentiation_ς.( exponent ) ]
+    end
+    # Method skeleton:
+    if triples.size == 1 && triples.first[-1] == 1 then
+      method_skeleton = "def #{ß}( exp=1 )\n" +
+                        "  %s\n" +
+                        "end"
+      method_body = "if exp == 1 then\n" +
+                    "  +( ::SY.Unit( :%s )%s ) * self\n" +
+                    "else\n" +
+                    "  +( ::SY.Unit( :%s )%s ) ** exp * self\n" +
+                    "end"
+      uς, pfxς, expς = process_triple.( *triples.shift )
+      method_body %= [uς, pfxς] * 2
+    else
+      method_skeleton = "def #{ß}\n" +
+                        "  %s\n" +
+                        "end"
+      factors = [ "+( ::SY.Unit( :%s )%s )%s * self" %
+                  process_triple.( *triples.shift ) ] +
+        triples.map do |ᴛ|
+          "( ::SY.Unit( :%s )%s.relative ) )%s" % process_triple.( *ᴛ )
+        end
+      # Multiply the factors toghether:
+      method_body = factors.join( " * \n    " )
+    end
+    # Return the finished method string:
+    return ( method_skeleton % method_body ).tap { |ς| puts ς if SY::DEBUG }
+  end
+
+  # Takes a token as the first argument, a symbol of the instance variable to
+  # be used for storage of active tokens, grabs the token, executes the
+  # supplied block, and releases the token. The method guards against double
+  # execution for the same token, raising IllegalRecursionError in such case.
+  # 
+  def anti_recursion_exec_with_token token, inst_var
+    registry = self.class.instance_variable_get( inst_var ) ||
+      self.class.instance_variable_set( inst_var, [] )
+    if registry.include? token then
+      raise SY::ExpressibleInUnits::RecursionError
+    end
+    begin
+      registry << token
+      yield if block_given?
+    ensure
+      registry.delete token
+    end
+  end
+
+  # FIXME: There should be an option to define by default, already at the
+  # beginning, certain methods for certain classes, to get in front of possible
+  # collisions. Collision was detected for example for #second with
+  # active_support/duration.rb
+end # module SY::UnitMethodsMixin

data/lib/sy/fixed_assets_of_the_module.rb

@@ -0,0 +1,287 @@
+#encoding: utf-8
+
+# Here, fixed assets of the main module are set up.
+# 
+module SY
+  # Basic physical dimensions.
+  # 
+  BASE_DIMENSIONS = {
+    L: :LENGTH,
+    M: :MASS,
+    Q: :ELECTRIC_CHARGE,
+    Θ: :TEMPERATURE,
+    T: :TIME
+  }
+
+  class << BASE_DIMENSIONS
+    # Letters of base dimensions.
+    # 
+    def letters
+      keys
+    end
+
+    # Base dimensions letters with prefixes.
+    # 
+    def prefixed_letters
+      [] # none for now
+    end
+
+    # Base dimension symbols – letters and prefixed letters.
+    # 
+    def base_symbols
+      @baseß ||= letters + prefixed_letters
+    end
+    alias basic_symbols base_symbols
+
+    # Takes an sps representing a dimension, and converts it to a hash of
+    # base dimension symbols => exponents.
+    # 
+    def parse_sps( sps )
+      _, letters, exponents = ::SY::SPS_PARSER.( sps, self.letters )
+      return Hash[ letters.map( &:to_sym ).zip( exponents.map( &:to_i ) ) ]
+    end
+  end
+
+  # Table of standard prefixes and their corresponding unit multiples.
+  # 
+  PREFIX_TABLE = [ { full: "exa", short: "E", factor: 1e18 },
+                   { full: "peta", short: "P", factor: 1e15 },
+                   { full: "tera", short: "T", factor: 1e12 },
+                   { full: "giga", short: "G", factor: 1e9 },
+                   { full: "mega", short: "M", factor: 1e6 },
+                   { full: "kilo", short: "k", factor: 1e3 },
+                   { full: "hecto", short: "h", factor: 1e2 },
+                   { full: "deka", short: "dk", factor: 1e1 },
+                   { full: "", short: "", factor: 1 },
+                   { full: "deci", short: "d", factor: 1e-1 },
+                   { full: "centi", short: "c", factor: 1e-2 },
+                   { full: "mili", short: "m", factor: 1e-3 },
+                   { full: "micro", short: "µ", factor: 1e-6 },
+                   { full: "nano", short: "n", factor: 1e-9 },
+                   { full: "pico", short: "p", factor: 1e-12 },
+                   { full: "femto", short: "f", factor: 1e-15 },
+                   { full: "atto", short: "a", factor: 1e-18 } ]
+
+
+  class << PREFIX_TABLE
+    # List of full prefixes.
+    # 
+    def full_prefixes
+      @full ||= map { |row| row[:full] }
+    end
+
+    # List of prefix abbreviations.
+    # 
+    def prefix_abbreviations
+      @short ||= map { |row| row[:short] }
+    end
+    alias short_prefixes prefix_abbreviations
+
+    # List of full prefixes and short prefixes.
+    # 
+    def all_prefixes
+      @all ||= full_prefixes + prefix_abbreviations
+    end
+
+    # Parses an SPS using a list of permitted unit symbols, currying it with
+    # own #all_prefixes.
+    # 
+    def parse_sps sps, unit_symbols
+      SY::SPS_PARSER.( sps, unit_symbols, all_prefixes )
+    end
+
+    # A hash of clue => corresponding_row pairs.
+    # 
+    def row clue
+      ( @rowꜧ ||= Hash.new do |ꜧ, key|
+          case key
+          when Symbol then
+            rslt = ꜧ[key.to_s]
+            ꜧ[key] = rslt if rslt
+          else
+            r = find { |r|
+              r[:full] == key || r[:short] == key || r[:factor] == key
+            }
+            ꜧ[key] = r if r
+          end
+        end )[ clue ]
+    end
+
+    # Converts a clue to a full prefix.
+    # 
+    def to_full clue
+      ( @fullꜧ ||= Hash.new do |ꜧ, key|
+          result = row( key )
+          result = result[:full]
+          ꜧ[key] = result if result
+        end )[ clue ]
+    end
+
+    # Converts a clue to a prefix abbreviation.
+    # 
+    def to_short clue
+      ( @shortꜧ ||= Hash.new do |ꜧ, key|
+          result = row( key )[:short]
+          ꜧ[key] = result if result
+        end )[ clue ]
+    end
+
+    # Converts a clue to a factor.
+    # 
+    def to_factor clue
+      ( @factorꜧ ||= Hash.new do |ꜧ, key|
+          result = row( key )[:factor]
+          ꜧ[key] = result if result
+        end )[ clue ]
+    end
+  end
+
+  # Unicode superscript exponents.
+  # 
+  SUPERSCRIPT = Hash.new { |ꜧ, key|
+    if key.is_a? String then
+      key.size <= 1 ? nil : key.each_char.map{|c| ꜧ[c] }.join
+    else
+      ꜧ[key.to_s]
+    end
+  }.merge! Hash[ '-/0123456789'.each_char.zip( '⁻⎖⁰¹²³⁴⁵⁶⁷⁸⁹'.each_char ) ]
+
+  # Reverse conversion of Unicode superscript exponents (from exponent
+  # strings to fixnums).
+  # 
+  SUPERSCRIPT_DOWN = Hash.new { |ꜧ, key|
+    if key.is_a? String then
+      key.size == 1 ? nil : key.each_char.map{|c| ꜧ[c] }.join
+    else
+      ꜧ[key.to_s]
+    end
+  }.merge!( SUPERSCRIPT.invert ).merge!( '¯' => '-', # other superscript chars
+                                         '´' => '/' )
+
+  # SPS stands for "superscripted product string", It is a string of specific
+  # symbols with or without Unicode exponents, separated by periods, such as
+  # "syma.symb².symc⁻³.symd.syme⁴" etc. This closure takes 2 arguments (array
+  # of symbols, and array of exponents) and produces an SPS out of them.
+  # 
+  SPS = lambda { |ßs, exps|
+    raise ArgumentError unless ßs.size == exps.size
+    exps = exps.map{|e| Integer e }
+    zipped = ßs.zip( exps )
+    clean = zipped.reject {|e| e[1] == 0 }
+    # omit exponents equal to 1:
+    clean.map{|ß, exp| "#{ß}#{exp == 1 ? "" : SUPERSCRIPT[exp]}" }.join "."
+  }
+
+  # Singleton #inspect method for SPS-making closure.
+  # 
+  def SPS.inspect
+    "Superscripted product string constructor lambda." +
+      "Takes 2 arguments. Example: [:a, :b], [-1, 2] #=> a⁻¹b²."
+  end
+
+  # A closure that parses superscripted product strings (SPSs). It takes 3
+  # arguments: a string to be parsed, an array of acceptable symbols, and
+  # an array of acceptable prefixes. It returns 3 equal-sized arrays: prefixes,
+  # symbols and exponents.
+  # 
+  SPS_PARSER = lambda { |input_ς, ßs, prefixes = []|
+    input_ς = input_ς.to_s.strip
+    ßs = ßs.map &:to_s
+    prefixes = ( prefixes.map( &:to_s ) << '' ).uniq
+    # input string splitting
+    input_ς_sections = input_ς.split '.'
+    if input_ς_sections.empty?
+      raise NameError, "Bad input string: '#{input_ς}'!" unless input_ς.empty?
+      return [], [], []
+    end
+    # analysis of input string sections
+    input_ς_sections.each_with_object [[], [], []] do |_section_, memo|
+      section = _section_.dup
+      superscript_chars = SUPERSCRIPT.values
+      # chop off the superscript tail, if any
+      section.chop! while superscript_chars.any? { |ch| section.end_with? ch }
+      # the set of candidate unit symbols
+      candidate_ßs = ßs.select { |ß| section.end_with? ß }
+      # seek candidate prefixes corresponding to candidate_ßs
+      candidate_prefixes = candidate_ßs.map { |ß| section[ 0..((-1) - ß.size) ] }
+      # see which possible prefixes can be confirmed
+      confirmed_prefixes = candidate_prefixes.select { |x| prefixes.include? x }
+      # complain if no symbol matches sec
+      raise NameError, "Unknown unit: '#{section}'!" if confirmed_prefixes.empty?
+      # pay attention to ambiguity in prefix/symbol pair
+      if confirmed_prefixes.size > 1 then
+        if confirmed_prefixes.any? { |x| x == '' } then # prefer empty prefixes
+          chosen_prefix = ''
+        else
+          raise NameError, "Ambiguity in interpretation of '#{section}'!"
+        end
+      else
+        chosen_prefix = confirmed_prefixes[0]
+      end
+      # Based on it, interpret the section parts:
+      unit_ς = section[ (chosen_prefix.size)..(-1) ]
+      suffix = _section_[ ((-1) - chosen_prefix.size - unit_ς.size)..(-1) ]
+      # Make the exponent string suffix into the exponent number:
+      exponent_ς = SUPERSCRIPT_DOWN[ suffix ]
+      # Complain if bad:
+      raise NameError, "Malformed exponent in #{_section_}!" if exponent_ς.nil?
+      exponent_ς = "1" if exponent_ς == '' # empty exponent string means 1
+      exp = Integer exponent_ς
+      raise NameError, "Zero exponents not allowed: #{exponent_ς}" if exp == 0
+      # and store the interpretation
+      memo[0] << chosen_prefix; memo[1] << unit_ς; memo[2] << exp
+      memo
+    end
+  }
+
+  # Singleton #inspect method for SPS-parsing closure.
+  # 
+  def SPS_PARSER.inspect
+    "Superscripted product string parser lambda. " +
+      "Takes 2 compulsory and 1 optional argument. Example: " +
+      '"kB.s⁻¹", [:g, :B, :s, :C], [:M, :k, :m, :µ] #=> ["k", ""], ' +
+      '["B", "s"], [1, -1]'
+  end
+
+  # Mainly for mixing incompatible quantities.
+  # 
+  class QuantityError < StandardError; end
+
+  # Mainly for mixing incompatible dimensions.
+  # 
+  class DimensionError < StandardError; end
+
+  # Mainly for negative or otherwise impossible physical amounts.
+  # 
+  class MagnitudeError < StandardError; end
+
+  # Convenience dimension accessor.
+  # 
+  def Dimension id=proc{ return ::SY::Dimension }.call
+    case id.to_s
+    when '', 'nil', 'null', 'zero', '0', '⊘', '∅', 'ø' then SY::Dimension.zero
+    else SY::Dimension.new id end
+  end
+
+  # Convenience quantity instance accessor.
+  # 
+  def Quantity id=proc{ return ::SY::Quantity }.call
+    SY::Quantity.instance id
+  end
+
+  # Convenience unit instance accessor.
+  # 
+  def Unit id=proc{ return ::SY::Unit }.call
+    SY::Unit.instance id
+  end
+
+  # Explicit magnitude constructor.
+  # 
+  def Magnitude args=proc{ return ::SY::Magnitude }.call
+    args.must_have :quantity, syn!: :of
+    qnt = args.delete :quantity
+    SY::Magnitude.of qnt, args
+  end
+
+  module_function :Dimension, :Quantity, :Unit, :Magnitude
+end

data/lib/sy/magnitude.rb

@@ -0,0 +1,515 @@
+#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.
+#
+# 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.
+# 
+module SY::Magnitude
+  class << self
+    # Constructor of absolute magnitudes of a given quantity.
+    # 
+    def absolute *args
+      ꜧ = args.extract_options!
+      qnt = ꜧ[:quantity] || ꜧ[:of] || args.shift
+      return qnt.absolute.magnitude ꜧ[:amount]
+    end
+
+    # Constructor of relative magnitudes of a given quantity.
+    # 
+    def difference *args
+      ꜧ = args.extract_options!
+      qnt = ꜧ[:quantity] || ꜧ[:of] || args.shift
+      return qnt.relative.magnitude ꜧ[:amount]
+    end
+
+    # Constructor of magnitudes of a given quantity.
+    # 
+    def of qnt, args={}
+      return qnt.magnitude args[:amount]
+    end
+
+    # Constructor of zero magnitude of a given quantity.
+    # 
+    def zero
+      return absolute 0
+    end
+  end
+
+  # Magnitudes are comparable.
+  # 
+  include Comparable
+
+  # Magnitudes respond to unit methods.
+  # 
+  include SY::ExpressibleInUnits
+
+  attr_reader :quantity, :amount
+  alias in_standard_unit amount
+
+  # Delegations to amount:
+  # 
+  delegate :zero?, to: :amount
+  delegate :to_f, to: :amount
+
+  # Delegations to quantity:
+  # 
+  delegate :dimension,
+           :dimensionless?,
+           :standard_unit,
+           :relative?,
+           :absolute?,
+           :magnitude,
+           :relationship,
+           to: :quantity
+
+  # Computes absolute value and reframes into the absolute quantity.
+  # 
+  def absolute
+    quantity.absolute.magnitude amount.abs
+  end
+
+  # Reframes into the relative quantity.
+  # 
+  def relative
+    quantity.relative.magnitude amount
+  end
+
+  # Reframes the magnitude into its relative quantity.
+  # 
+  def +@
+    quantity.relative.magnitude( amount )
+  end
+
+  # Reframes the magnitude into its relative quantity, with negative amount.
+  # 
+  def -@
+    quantity.relative.magnitude( -amount )
+  end
+
+  # Absolute value of a magnitude (no reframe).
+  # 
+  def abs
+    magnitude amount.abs
+  end
+
+  # Rounded value of a Magnitude: A new magnitude with rounded amount.
+  # 
+  def round *args
+    magnitude amount.round( *args )
+  end
+
+  # Compatible magnitudes compare by their amounts.
+  # 
+  def <=> m2
+    return amount <=> m2.amount if quantity == m2.quantity
+    raise SY::QuantityError, "Mismatch: #{quantity} <=> #{m2.quantity}!"
+  end
+
+  # Addition.
+  # 
+  def + m2
+    return magnitude amount + m2.amount if quantity == m2.quantity
+    # return self if m2 == SY::ZERO
+    raise SY::QuantityError, "Mismatch: #{quantity} + #{other.quantity}!"
+  end
+
+  # Subtraction.
+  # 
+  def - m2
+    return magnitude amount - m2.amount if quantity == m2.quantity
+    # return self if m2 == SY::ZERO
+    raise SY::QuantityError, "Mismatch: #{quantity} - #{m2.quantity}!"
+  end
+
+  # Multiplication.
+  # 
+  def * m2
+    case m2
+    when Numeric then
+      magnitude amount * m2
+    # when SY::ZERO then
+    #   return magnitude 0
+    else
+      ( quantity * m2.quantity ).magnitude( amount * m2.amount )
+    end
+  end
+
+  # Division.
+  # 
+  def / m2
+    case m2
+    when Numeric then
+      magnitude amount / m2
+    # when SY::ZERO then
+    #   raise ZeroDivisionError, "Attempt to divide #{self} by #{SY::ZERO}."
+    else
+      ( quantity / m2.quantity ).magnitude( amount / m2.amount )
+    end
+  end
+
+  # Exponentiation.
+  # 
+  def ** exp
+    case exp
+    when SY::Magnitude then
+      raise SY::DimensionError, "Exponent must have zero dimension! " +
+        "(exp given)" unless exp.dimension.zero?
+      ( quantity ** exp.amount ).magnitude( amount ** exp.amount )
+    else
+      ( quantity ** exp ).magnitude( amount ** exp )
+    end
+  end
+
+  # Type coercion for magnitudes.
+  # 
+  def coerce m2
+    case m2
+    when Numeric then return SY::Amount.relative.magnitude( m2 ), self
+    else
+      raise TErr, "#{self} cannot be coerced into a #{m2.class}!"
+    end
+  end
+
+  # Gives the magnitude as a plain number in multiples of another magnitude,
+  # supplied as argument. The quantities must match.
+  # 
+  def in m2
+    case m2
+    when Symbol, String then
+      begin
+        self.in eval( "1.#{m2}" ).aT_kind_of SY::Magnitude # digest it
+      rescue TypeError
+        raise TypeError, "Evaluating 1.#{m2} does not result in a magnitude; " +
+          "method collision with another library?"
+      end
+    when SY::Magnitude then
+      return amount / m2.amount if quantity == m2.quantity
+      amount / m2.( quantity ).amount # reframe before division
+    else
+      raise TypeError, "Unexpected type for Magnitude#in method! (#{m2.class})"
+    end
+  end
+
+  # Reframes a magnitude into a different quantity. Dimension must match.
+  # 
+  def reframe q2
+    case q2
+    when SY::Quantity then q2.import self
+    when SY::Unit then q2.quantity.import self
+    else raise TypeError, "Unable to reframe into a #{q2.class}!" end
+  end
+
+  # Reframes a magnitude into a <em>relative</em> version of a given quantity.
+  # (If absolute quantity is supplied as an argument, its relative colleague
+  # is used to reframe.)
+  # 
+  def call q2
+    case q2
+    when SY::Quantity then q2.relative.import self
+    when SY::Unit then q2.quantity.relative.import self
+    else raise TypeError, "Unable to reframe into a #{q2.class}!" end
+  end
+
+  # True if amount is negative. Implicitly false for absolute quantities.
+  # 
+  def negative?
+    amount < 0
+  end
+
+  # Opposite of #negative?. Implicitly true for absolute quantities.
+  # 
+  def nonnegative?
+    amount >= 0
+  end
+
+  # Gives the magnitude written "naturally", in its most favored units.
+  # It is also possible to supply a unit in which to show the magnitude
+  # as the 1st argument (by default, the most favored unit of its
+  # quantity), or even, as the 2nd argument, the number format (by default,
+  # 3 decimal places).
+
+
+  # further remarks: depending on the area of science the quantity
+  # is in, it should have different preferences for unit presentation.
+  # Different areas prefer different units for different dimensions.
+  
+  # For example, if the quantity is "Molarity²", its standard unit will
+  # be anonymous and it magnitudes of this quantity should have preference
+  # for presenting themselves in μM², or in mΜ², or such
+  
+  # when attempting to present number Molarity².amount 1.73e-7.mM
+  
+
+  # 
+  def to_s( unit=quantity.units.first || quantity.standard_unit,
+            number_format=default_amount_format )
+    # step 1: produce pairs [number, unit_presentation],
+    #         where unit_presentation is an array of triples
+    #         [prefix, unit, exponent], which together give the
+    #         correct dimension for this magnitude, and correct
+    #         factor so that number * factor == self.amount
+    # step 2: define a goodness function for them
+    # step 3: define a satisfaction criterion
+    # step 4: maximize this goodness function until the satisfaction
+    #         criterion is met
+    # step 5: interpolate the string from the chosen choice
+    
+    # so, let's start doing it
+    # how do we produce the first choice?
+    # if the standard unit for this quantity is named, we'll start with it
+    
+    # let's say that the abbreviation of this std. unit is Uu, so the first
+    # choices will be:
+    # 
+    #                        amount.Uu
+    #                        (amount * 1000).µUu
+    #                        (amount / 1000).kUu
+    #                        (amount * 1_000_000).nUu
+    #                        (amount / 1_000_000).MUu
+    #                        ...
+    #                        
+    # (let's say we'll use only short prefixes)
+    #
+    # which one do we use?
+    # That depends. For example, CelsiusTemperature is never rendered with
+    # SI prefixes, so their cost should be +Infinity
+    # 
+    # Cost of the number could be eg.:
+    #
+    #          style:                cost:
+    #          3.141                 0
+    #          31.41, 314.1          1
+    #          0.3141                2
+    #          3141.0                3
+    #          0.03141               4
+    #          31410.0               5n
+    #          0.003141              6
+    #          ...
+    #          
+    # Default cost of prefixes could be eg.
+    #
+    #          unit representation:  cost:
+    #          U                     0
+    #          dU                    +Infinity
+    #          cU                    +Infinity
+    #          mU                    1
+    #          dkU                   +Infinity
+    #          hU                    +Infinity
+    #          kU                    1
+    #          µU                    2
+    #          MU                    2
+    #          nU                    3
+    #          GU                    3
+    #          pU                    4
+    #          TU                    4
+    #          fU                    5
+    #          PU                    5
+    #          aU                    6
+    #          EU                    6
+    #
+    # Cost of exponents could be eg. their absolute value, and +1 for minus sign
+    #
+    # Same unit with two different prefixes may never be used (cost +Infinity)
+    #
+    # Afterwards, there should be cost of inconsistency. This could be implemented
+    # eg. as computing the first 10 possibilities for amount: 1 and giving them
+    # bonuses -20, -15, -11, -8, -6, -5, -4, -3, -2, -1. That would further reduce the variability of the
+    # unit representations.
+    #
+    # Commenting again upon default cost of prefixes, prefixes before second:
+    #
+    #          prefix:               cost:
+    #          s                     0
+    #          ms                    4
+    #          ns                    5
+    #          ps                    6
+    #          fs                    7
+    #          as                    9
+    #          ks                    +Infinity
+    #          Ms                    +Infinity
+    #          ...
+    #
+    # Prefixes before metre
+    #
+    #          prefix:               cost:
+    #          m                     0
+    #          mm                    2
+    #          µm                    2
+    #          nm                    3
+    #          km                    3
+    #          Mm                    +Infinity
+    #          ...
+    #          
+
+    # number, unit_presentation = choice
+
+    begin
+      
+      un = unit.short || unit.name
+      
+      if un then
+        number = self.in unit
+        number_ς = number_format % number
+        
+        prefix = ''
+        exp = 1
+        # unit_presentation = prefix, unit, exp
+        
+        unit_ς = SY::SPS.( [ "#{prefix}#{unit.short}" ], [ exp ] )
+        
+        [ number_ς, unit_ς ].join '.'
+      else
+        number = amount
+        # otherwise, use units of component quantities
+        ꜧ = quantity.composition.to_hash
+        symbols, exponents = ꜧ.each_with_object Hash.new do |pair, memo|
+          qnt, exp = pair
+          if qnt.standard_unit.name
+            std_unit = qnt.standard_unit
+            memo[ std_unit.short || std_unit.name ] = exp
+          else
+            m = qnt.magnitude( 1 ).to_s
+            memo[ m[2..-1] ] = exp
+            number = m[0].to_i * number
+          end
+        end.to_a.transpose
+        # assemble SPS
+        unit_ς = SY::SPS.( symbols, exponents )
+        # interpolate
+        number_ς = number_format % number
+        return number_ς if unit_ς == '' || unit_ς == 'unit'
+        [ number_ς, unit_ς ].join '.'
+      end
+      
+    rescue
+      number_ς = number_format % amount
+      [ number_ς, "unit[#{quantity}]" ].join '.'
+    end
+  end
+
+  # def to_s unit=quantity.units.first, number_format='%.3g'
+  #   begin
+  #     return to_string( unit ) if unit and unit.abbreviation
+  #   rescue
+  #   end
+  #   # otherwise, use units of basic dimensions – here be the magic:
+  #   hsh = dimension.to_hash
+  #   symbols, exponents = hsh.each_with_object Hash.new do |pair, memo|
+  #     dimension_letter, exponent = pair
+  #     std_unit = SY::Dimension.basic( dimension_letter ).standard_unit
+  #     memo[ std_unit.abbreviation || std_unit.name ] = exponent
+  #   end.to_a.transpose
+  #   # assemble the superscripted product string:
+  #   sps = SY::SPS.( symbols, exponents )
+  #   # and finally, interpolate the string
+  #   "#{number_format}#{sps == '' ? '' : '.' + sps}" % amount
+  #   "#{amount}#{sps == '' ? '' : '.' + sps}"
+  # end
+  
+  # Inspect string of the magnitude
+  # 
+  def inspect
+    "#<#{çς}: #{self} >"
+  end
+
+  # Without arguments, it returns a new magnitude equal to self. If argument
+  # is given, it is treated as factor, by which the amount is to be muliplied.
+  # 
+  def to_magnitude
+    magnitude( amount )
+  end
+
+  private
+
+  # Gives the amount of standard quantity corresponding to this magnitude,
+  # if such conversion is possible.
+  # 
+  def to_amount_of_standard_quantity
+    return amount if quantity.standard?
+    amount * quantity.relationship.to_amount_of_standard_quantity
+  end
+
+  def same_dimension? other
+    case other
+    when SY::Magnitude then dimension == other.dimension
+    when Numeric then dimension.zero?
+    when SY::Quantity then dimension == other.dimension
+    when SY::Dimension then dimension == other
+    else
+      raise TErr, "The object (#{other.class} class) does not " +
+        "have dimension comparable to SY::Dimension defined"
+    end
+  end
+
+  def same_quantity? other
+    case other
+    when SY::Quantity then quantity == other
+    else
+      begin
+        quantity == other.quantity
+      rescue NoMethodError
+        raise TErr, "#{other} does not have quantity!"
+      end
+    end
+  end
+
+  # The engine for constructing #to_s strings.
+  # 
+  def construct_to_s( named_unit=default_named_unit,
+                      number_format=default_amount_format )
+    name = named_unit.name.tE "must exist", "the unit name"
+    abbrev_or_name = named_unit.short || name
+    "#{number_format}.#{ str == '' ? unit : str }" %
+      numeric_value_in( unit )
+  end
+
+  def to_s_with_unit_using_abbreviation named_unit=default_named_unit
+    "%s.#{named_unit.abbreviation}"
+  end
+
+  def to_s_with_unit_using_name
+    # FIXME
+  end
+
+  # Error complaint about incompatible dimensions.
+  # 
+  def dim_complaint obj1=self, obj2
+    "#{obj1} not of the same dimension as #{obj2}!"
+  end
+
+  # String describing this class.
+  # 
+  def çς
+    "Magnitude"
+  end
+
+  # Default named unit to be used in expressing this magnitude.
+  # 
+  def default_named_unit
+    standard_unit
+  end
+
+  # Default format string for expressing the amount of this magnitude.
+  # 
+  def default_amount_format
+    "%.#{amount_formatting_precision}g"
+  end
+
+  def amount_formatting_precision
+    @amount_formatting_precision ||= default_amount_formatting_precision
+  end
+
+  def default_amount_formatting_precision
+    3
+  end
+end