Quantity.rb: Units and Quantities for Ruby

Quantity.rb provides first-class support for units and quantities in Ruby. The right abstractions for true quantity representation and complex conversions. Hopefully this readme will be all you need, but there are yardocs

require 'quantity/all'
1.meter                                                 #=> 1 meter
1.meter.to_feet                                         #=> 3.28083... foot
c = 299792458.meters / 1.second                         #=> 299792458 meter/second

newton = 1.meter * 1.kilogram / 1.second**2             #=> 1 meter*kilogram/second^2
newton.to_feet                                          #=> 3.28083989501312 foot*kilogram/second^2
newton.convert(:feet)                                   #=> 3.28083989501312 foot*kilogram/second^2
jerk_newton = newton / 1.second                         #=> 1 meter*kilogram/second^3
jerk_newton * 1.second == newton                        #=> true

mmcubed = 1.mm.cubed                                    #=> 1 millimeter^3
mmcubed * 1000 == 1.milliliter                          #=> true

[1.meter, 1.foot, 1.inch].sort                          #=> [1 inch, 1 foot, 1 meter]

m_to_f = Quantity::Unit.for(:meter).convert_proc(:feet)
m_to_f.call(1)                                          #=> 3.28083... (or a Rational)

Quantity.rb provides full-featured support for quantities, units, and dimensions in Ruby. Some terminology:

• Quantity: An amount of a unit, such as 12 meters.
• Unit: An amount of a given dimension to be measured, such as 'meter'
• Dimension: Some base quantity to be measured, such as 'length'

Quantities perform complete mathematical operations over their units, including +, -, \*, /, **, %, abs, divmod, <=>, and negation. Units and the dimensions they measure are fully represented and support * and /.

Quantity extends Numeric to allow easy creation of quantities, but there are direct interfaces to the library as well.

1.meter                == Quantity.new(1,Quantity::Unit.for(:meter)) 
1.meter.unit           == Quantity::Unit.for(:meter)
1.meter.unit.dimension == Quantity::Dimension.for(:length)

See the units section for supported units, and how to add your own.

Quantities are first-class citizens which do a fair job of imitating Numeric. Quantities support coerce, and can thus be used in almost any situation a numeric can:

2.5 + 5.meters    # => 7.5 meters
5 == 5.meters     # => true

Quantity.rb is not ready for production use for some areas, but should be fine for simple conversion use cases. If it breaks, please email the author for a full refund.

Specifically broken in this version are some operations on named higher dimensions:

1.liter / 1.second                      #=> should be 1 liter/second, but explodes
1.liter.convert(:'mm^3') / 1.second     #=> 1000000.0 millimeter^3/second

If you just work with units derived from the base dimensions, there aren't known bugs. Please add a spec if you find one.

• Lots more units are planned.
• BigDecimal support a la Rational.
• Supporting lambdas for unit values
• BigDecimal/Rational compatible values for existing units
• Some DSL sugar for adding derived dimension units

Quantity.rb comes with a sizable collection of units, but still needs significant expansion.

A number of base unit sets exist: require 'quantity/all' #=> load everything. uses US versions of foot, lb, etc require 'quantity/systems/si' #=> load SI require 'quantity/systems/us' #=> load US versions of foot, lb, etc require 'quantity/systems/imperial' #=> load British versions of foot, lb, etc require 'quantity/systems/information' #=> bits, bytes, and all that require 'quantity/systems/enumerable' #=> countable things--dozen, score, etc

Note that US and Imperial conflict with each other. Loading both is unsupported.

Adding your own units is simple:

Quantity::Unit.add_unit :furlong, :length, 201168, :furlongs
1.furlong  #=> 1 furlong

201168 represents 1 furlong in millimeters. Each base dimension, such as length, time, current, temperature, etc, is represented by a reference unit, which is generally the milli-version of the SI unit referencing that domain. NIST has an explanation of how the SI system works, and how all units are actually derived from very few.

All units for derived dimensions used the derived reference unit. For example, length is referenced to millimeters, so each unit of length is defined in terms of them:

Quantity::Unit.add_unit :meter, :length, 1000
Quantity::Unit.add_unit :millimeter, :length, 1, :mm

Thus, the base unit for volume is 1 mm^3: volume = Quantity::Dimension.add_dimension length3, :volume ml = Quantity::Dimension.add_unit :milliliter, :volume, 1000, :ml, :milliliters 1.mm3 * 1000 == 1.milliliter #=> true

See the bugs section for some current issues using units defined on derived dimensions.

The full list of included base dimensions and their reference units: * :length => :millimeter * :time => :millisecond * :current => :milliampere * :luminosity => :millicandela * :substance => :millimole * :temperature => :millikelvin * :mass => :milligram * :information => :bit # use :megabytes and :mebibytes * :quantity => :item # for countable quantities. units include 1.dozen, for example * :currency => :dollar # These are not really implemented yet

To determine the base unit for a derived dimension, you can use Quantity.rb itself:

force = Quantity::Dimension.for(:force)
newton = 1.meter * 1.kilogram / 1.second**2
newton.measures == force #=> true
newton_value = newton.to_mm.to_mg.to_ms  #=> 1000.0 millimeter*milligram/millisecond^2

Thus, a newton would be 1000 when added specifically:

Quantity::Unit.add_unit :newton, :force, 1000, :newtons
1.newton  == newton   #=> true

A dimension is a measurable thing, often called a 'base quantity' in scientific literature, but Quantity.rb specifically avoids that nomenclature, reserving 'quantity' for the class representing a unit and a value. As always, wikipedia has the answers.

Dimensions are not very useful by themselves, but you can play with them if you want.

length = Quantity::Dimension.for(:length)
time = Quantity::Dimension.for(:time)
speed = length / time

A number of dimensions are enabled by default (see dimension/base.rb).

A DSL of sorts is provided for declaring dimensions:

length  = Quantity::Dimension.add_dimenson :length
area    = Quantity::Dimension.add_dimension length**2, :area

length = Quantity::Dimension.for(:length)
area   = Quantity::Dimension.for(:area)
area == length * length                   #=> true

Quantity::Dimension is extended with empty subclasses for some base dimensions, so you can do pattern patching on the class:

case 1.meter.measures
  when Quantity::Dimension::Length
    puts "I am printed"
end

Quantity.rb provides you the ability to intuitively create the conversions your application needs, and then bypass the rest of the library.

m_to_f = 1.meter.measures.convert_proc(:feet)
m_to_f.call(5)    # => 5 meters in feet

This Proc object has been broken down into a single division; it no longer references any units, dimensions, or quantities. It's hard to be faster in pure Ruby.

By default, whatever Numeric you are using will be the stored value for the quantity.

5.meters
Rational(5).meters
5.0.meters

This value will be held. However, divisions are required for conversions, and the default is to force values into floats.

If accuracy is required, just require 'rational'. If Rational is defined, you'll get rationals instead of divided floats everywhere. In tests, this is an order of magnitude slower.

This is by no means the first unit conversion/quantity library for Ruby, but none of the existing ones scratched my itch just right. My goal is that this will be the last one I (and you) need. The abstractions go all the way down, and any conceivable conversion or munging functionality should be buildable on top of this.

Inspiration comes from:

• Quanty Why oh why did they involve yacc?
• Ruby Units
• Alchemist

• Ben Lavender - http://bhuga.net/
• Arto Bendiken - http://ar.to/
• Matt Todd - http://maraby.org/ License

Quantity.rb is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.