Phys-Units
GNU Units -compatible Ruby library for unit conversion of physical quantities. Major features: (1) It uses rich database of GNU Units. (2) It provides normal class interface without modifying built-in classes. Former name is Quanty, the first Ruby units library released in 2001.
Installation
Install from gem as:
$ gem install phys-units
Or install from source tree:
$ ruby setup.rb
Load Phys-Units library in your Ruby script:
require 'phys/units'
Overview
Phys::Quantity
is the primary class of Phys-Units library. This class represents Physical Quantities with a Unit of measurement. It contains Value and Unit.
Value of the quantity is given as the first parameter of Quantity constructor (alias is
Quantity[]). It must be a class instance having arithmetic methods, but it is not necessary to be a Numeric. This is a duck typing way.Phys::Quantity[2.5,"miles"].value #=> 2.5Unit is an instance of Phys::Unit class. It is created from the second argument of Quantity constructor.
Phys::Quantity[2.5,"miles"].unit #=> #<Phys::Unit 1609.344,{"m"=>1},@expr="5280 ft">
Phys::Unit
is a class to represent Physical Units of measurement. This class is used in the Phys::Quantity for calculations with Units. It has Factor and Dimension:
Factor of the unit is a scale factor relative to its base unit.
Phys::Unit["km"].factor #=> 1000Dimension of the unit is a hash table containing base units and dimensions as key-value pairs.
Phys::Unit["N"].dimension #=> {"kg"=>1, "m"=>1, "s"=>-2}
Examples
require "phys/units"
Q = Phys::Quantity
U = Phys::Unit
Q[1.23,'km'] + Q[4.56,'m'] #=> Phys::Quantity[1.23456,'km']
Q[123,'mile'] / Q[2,'hr'] #=> Phys::Quantity[61,'mile/hr']
Q[61,'miles/hr'].want('m/s') #=> Phys::Quantity[27.26944,'m/s']
Q[1.0,'are'] == Q[10,'m']**2 #=> true
Q[70,'tempF'] + Q[10,'degC'] #=> Phys::Quantity[88,'tempF']
Q[20,'tempC'].want('tempF') #=> Phys::Quantity[68,'tempF']
Math.cos(Q[60,'degree'].to_f) #=> 0.5
U["m/s"] === Q[1,'miles/hr'] #=> true
case Q[1,"miles/hr"]
when U["LENGTH"]
puts "length"
when U["TIME"]
puts "time"
when U["VELOCITY"]
puts "velocity"
else
puts "other"
end #=> "velocity"
Features
Phys-Units library is differentiated from many other units libraries for Ruby, by the following features:
- Compatible with GNU Units except currency and nonlinear units.
- Provides 2331 units, 85 prefixes, including UTF-8 unit names.
- Defines Units by reading GNU Units text data (See load_units.rb), unlike other libraries which define Units in Ruby code.
- Provides orthodox design of class interface.
- No addition or modification to Ruby standard classes in standard usage, to avoid conflicts with other libraries.
- Calculation of values is through Ruby Numeric arithmetic methods. Phys-Units does not care it.
- Conversion factors are internally held in Rational form even defined as the decimal form such as `1.0e10'.
- PI number has a dimension.
- Japanese Units are available by require 'phys/units/jp'.
Appendix Feature
Mix-in feature provides a simple unit calculator. Note that this usage involves global changes on a build-in class and will cause conflicts with other libraries.
$ irb -r phys/units/mixin
irb> 2.5.miles/hr >> m/s
=> Phys::Quantity[1.1176,"m/s"]
irb> 23.tempC >> tempF
=> Phys::Quantity[73.4,"tempF"]
irb> print_units LENGTH
m !
meter m
LENGTH meter
:
irb> print_units ENERGY
joule N m
J joule
prout 185.5 keV
:
Platforms tested
- ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-linux]
History
- 2017-10-24 ver 1.0.0
- Unit data from GNU Units version 2.14 (including 2014 CODATA recommended values)
- 2013-04-27 ver 0.9.0
- Change module name from Quanty to Phys-Units.
- Unit data from GNU Units version 2.04 (including 2010 CODATA recommended values)
Copying License
This program is free software. You can distribute/modify this program under the same terms as GPL3. See "COPYING" file. NO WARRANTY.
Author
Masahiro TANAKA