unitconv

Conversion of units of measurement.

Documentation

The unitconv library is an implementation of unit conversion routines based on the paper by Gordon S. Novak:

Conversion of Units of Measurement. IEEE Trans. on Software Engineering, vol. 21, no. 8 (Aug. 1995), pp. 651-661.

(Available online at http://www.cs.utexas.edu/users/novak/units95.html).

Correctness of unit conversion is established by the technique of dimensional analysis: the source and goal units must have the same dimensions. Following Novak, this extension defines a dimension as an 8-vector of integral powers of the following base quantities:

 (define-base-quantity  Unity          0)
 (define-base-quantity  Length         dimvals[0])
 (define-base-quantity  Time           dimvals[1])
 (define-base-quantity  Temperature    dimvals[2])
 (define-base-quantity  Mass           dimvals[3])
 (define-base-quantity  Current        dimvals[4])
 (define-base-quantity  Luminosity     dimvals[5])
 (define-base-quantity  Substance      dimvals[6])
 (define-base-quantity  Currency       dimvals[7])
 (define-base-quantity  Information    dimvals[8])

The unit conversion routine uses dimension integers to check that the requested unit conversion is legitimate. For example, the conversion from kilograms to meters illegal. Consequently, the dimensionality of each unit must be specified when the unit is declared.

 ;; Syntax is (define-unit name quantity factor abbreviation ...)
 
 ;; define units of length
 (define-unit meter     Length 1.0       m meters)
 (define-unit inch      Length 254/10000 in inches)
 
 ;; define units of mass and time
 (define-unit kilogram  Mass   1.0       kg kilograms)
 (define-unit second    Time   1.0       s seconds)
 
 ;; define two new derived quantities: acceleration and force
 (define-quantity   Acceleration  (/ Length (** Time 2)))
 (define-quantity   Force         (* Mass Acceleration))
 
 ;; define a unit of force
 (define-unit newton       Force (/ (* kilogram meter) (* second second)) nt newtons)

Now only conversion between units of the same dimensionality is permitted:

 (unit-convert meter inch 1) ->  5000/127
 (unit-convert meter inch 2 3 4) ->  (10000/127 15000/127 20000/127)
 
 (unit-convert meter kilogram 1)
 Error: (unitconv) unit-convert : given units are of different dimensions: 
  source= #(unit meter (m meters) [Length] 1.0) ; 
  dest=  #(unit kilogram (kg kilograms) [Mass] 1.0)

Procedures and Macros

unit-convert:: SRC * DEST * [VAL1 ...] -> (FACTOR1 ... )

Converts the given numeric values expressed in unit SRC to their equivalents in unit DEST.

Arguments SRC, DEST are records of type unit. See the definitions below for information about the units that are defined by this extension, as well as for information about creating new units.

unit-equal?:: UNIT1 * UNIT2 -> BOOL Returns true if the two units have the same dimension and factor, false otherwise.

(define-quantity name expr)

Defines a derivative quantity NAME.

EXPR is an S-expression with the following syntax:

quantity-expr ::= base-quantity | derived-quantity | (* quantity-expr quantity-expr) | (* quantity-expr integer) | (/ quantity-expr quantity-expr) | (/ quantity-expr integer) | (** quantity-expr integer)

where

• base-quantity : one of the predefined base quantities
• derived-quantity : a quantity created by define-quantity
• ** : exponentiation operator

(define-unit name dims factor . abbrevs)

Defines a variable NAME that holds a unit definition of a unit with the given dimension and factor.

DIMS can be either one of the base quantities (see next section) or a derivative quantity created by define-quantity.

(define-prefix-unit unit prefix . abbrevs)

Defines a variable whose name is the concatenated PREFIX and UNIT and that holds a unit definition of the given unit and prefix.

Predefined Quantities

Base Quantities

• Unity (dimensionless)
• Length
• Time
• Temperature
• Mass
• Current
• Luminosity
• Substance
• Currency
• Information

Derived Quantities

Geometry

• Area : (** Length 2)
• Volume : (** Length 3)

Mechanics

• Velocity : (/ Length Time)
• Acceleration : (/ Length (** Time 2))
• Force : (* Mass Acceleration)
• Pressure : (/ Force Area)
• Energy : (* Force Length)
• Power : (/ Energy Time)

Electricity

• Charge : (* Current Time)
• Potential : (/ Energy Charge)
• Capacitance : (/ Charge Potential)
• Resistance : (/ Potential Current)
• Conductance : (/ Current Potential)
• Inductance : (/ (* Potential Time) Current)

Electromagnetism

• Magnetic-Flux : (/ (* Mass Area) (* (** Time 2) Current))
• Magnetic-Flux-Density : (/ Mass (* (** Time 2) Current))
• Magnetic-Field-Strength : (/ Current Length)

Chemistry

• Concentration : (/ Substance Volume)
• Density : (/ Mass Volume)

Optics

• Luminance : (/ Luminosity Area)

Other

• Frequency : (/ Unity Time)
• Rate : (/ Information Time)

Predefined Units

SI Unit Prefixes

Abbreviation(s)

Name	Quantity	Factor
yocto	Unity	1e-24
zepto	Unity	1e-21
atto	Unity	1e-18
femto	Unity	1e-15
pico	Unity	1e-12
nano	Unity	1e-09
micro	Unity	1e-06
milli	Unity	0.001
centi	Unity	0.01
deci	Unity	0.1
deca	Unity	10.0
hecto	Unity	100
kilo	Unity	1000
mega	Unity	1000000
giga	Unity	1000000000
tera	Unity	1000000000000
peta	Unity	1e+15
exa	Unity	1e+18
zetta	Unity	1e+21
yotta	Unity	1e+24

IEC Standard Prefixes

Name	Quantity	Factor	Abbreviation(s)
kibi	Unity	1024
mebi	Unity	1048576
gibi	Unity	1073741824
tebi	Unity	1099511627776
pebi	Unity	1125899906842624
exbi	Unity	1152921504606846976
zebi	Unity	1180591620717411303424
yobi	Unity	1208925819614629174706176

Time Multiples

Name	Quantity	Factor	Abbreviation(s)
twelve	Unity	12
sixty	Unity	60

Angles

Name	Quantity	Factor	Abbreviation(s)
Name	Quantity	Factor	Abbreviation(s)
radian	Unity	1.0	(rad radians)
degree	Unity	(/ pi 180)	(deg degrees)

Units of Length

Name	Quantity	Factor	Abbreviation(s)
meter	Length	1.0	(m meters)
inch	Length	254/10000	(in inches)
foot	Length	3048/10000	(ft feet)
angstrom	Length	1e-10	(ang angstroms)
astronomical-unit	Length	149597870700	(au)
parsec	Length	(* (/ 648000 pi) au)	(parsecs)

Units of Area and Volume

Name	Quantity	Factor	Abbreviation(s)
square-meter	Area	(* meter meter)	(m^2 m2 meter-squared meters-squared square-meters)
square-inch	Area	(* inch inch)	(in^2 inch-squared inches-squared square-inches)
square-micron	Area	(* micrometer micrometer)	(um^2 micrometer-squared micrometers-squared micron-squared microns-squared square-microns)
square-millimeter	Area	(* millimeter millimeter)	(mm^2 millimeter-squared millimeters-squared square-millimeters)
cubic-meter	Volume	(* meter (* meter meter))	(m^3 meter-cubed meters-cubed cubic-meters)
liter	Volume	(* 0.001 cubic-meter)	(L litre liters)

Units of Mass

Name	Quantity	Factor	Abbreviation(s)
kilogram	Mass	1.0	(kg kilograms)
gram	Mass	1/1000	(g grams)
pound	Mass	(* gram 45359237/100000)	(lb pounds)
slug	Mass	(* pound 3217405/100000)	(slugs)
atomic-mass-unit	Mass	1.6605402e-27	(amu atomic-mass-units)

Units of Time

Name	Quantity	Factor	Abbreviation(s)
second	Time	1.0	(s seconds)
hour	Time	(* sixty (* sixty second))	(h hrs hours)
minute	Time	(* sixty second)	(minutes)
day	Time	(* 24 hour)	(days)
week	Time	(* 7 day)	(weeks)

Units of Acceleration

Name	Quantity	Factor	Abbreviation(s)
meters-per-second-squared	Acceleration	(/ meter (* second second))	(m/s2 m/s^2 m/sec2 m/sec^2)

Units of Frequency

Name	Quantity	Factor	Abbreviation(s)
hertz	Frequency	1.0	(hz)

Units of Force

Name	Quantity	Factor	Abbreviation(s)
newton	Force	(/ (* kilogram meter) (* second second))	(nt newtons)
pound-force	Force	(/ (* slug foot) (* second second))	(lbf)

Units of Power

Name	Quantity	Factor	Abbreviation(s)
watt	Power	(/ (* kilogram meter meter) (* second second second))	(W watts)
horsepower	Power	(* 550 (/ (* foot pound-force) second))	(hp)

Units of Energy

Name	Quantity	Factor	Abbreviation(s)
joule	Energy	(* newton meter)	(J joules)
electron-volt	Energy	(* 1.60217733e-19 joule)	(ev electron-volts)
kilowatt-hour	Energy	(* kilo (* watt hour))	(kwh kilowatt-hours)
calorie	Energy	(* 4184/1000 joule)	(cal calories)
erg	Energy	(* 1e-07 joule)	(ergs)
british-thermal-unit	Energy	(* 1055056/1000 joule)	(btu btus)

Units of Current

Name	Quantity	Factor	Abbreviation(s)
ampere	Current	1.0	(A amp amps amperes)

Units of Electric Charge

Name	Quantity	Factor	Abbreviation(s)
coulomb	Charge	(* ampere second)	(C coulombs)

Units of Electric Potential

Name	Quantity	Factor	Abbreviation(s)
volt	Potential	(/ (* kilogram meter meter) (* ampere second second second))	(V volts)

Units of Resistance

Name	Quantity	Factor	Abbreviation(s)
ohm	Resistance	(/ volt ampere)	(ohms)

Units of Capacitance

Name	Quantity	Factor	Abbreviation(s)
farad	Capacitance	(/ coulomb volt)	(F farads)

Units of Conductance

Name	Quantity	Factor	Abbreviation(s)
siemens	Conductance	(/ ampere volt)	(S mho)

Units of Inductance

Name	Quantity	Factor	Abbreviation(s)
henry	Inductance	(/ (* meter meter kilogram) (* ampere ampere second second))	(H)

Units of Magnetic Flux

Name	Quantity	Factor	Abbreviation(s)
tesla	Magnetic-Flux-Density	(/ kilogram (* ampere second second))	(T teslas)
weber	Magnetic-Flux	(/ (* kilogram meter meter) (* ampere second second))	(wb webers)

Units of Magnetic Field Strength

Name	Quantity	Factor	Abbreviation(s)
ampere-per-meter	Magnetic-Field-Strength	(/ ampere meter)	(amperes-per-meter)

Units of Substance

Name	Quantity	Factor	Abbreviation(s)
mole	Substance	1.0	(mol moles)

Units of Density

Name	Quantity	Factor	Abbreviation(s)
rho	Density	(/ kilogram cubic-meter)

Units of Concentration

Name	Quantity	Factor	Abbreviation(s)
molarity	Concentration	(/ mole liter)	(M mol/L)
parts-per-million	Concentration	(/ milligram kilogram)	(ppm)

Units of Temperature

Name	Quantity	Factor	Abbreviation(s)
degK	Temperature	1.0	(K)

Units of Information

Name	Quantity	Factor	Abbreviation(s)
bit	Information	1	(b bits shannon shannons Sh)
byte	Information	8	(B bytes)
nat	Information	1.44269504088896	(nats nit nits nepit nepits)
ban	Information	3.32192809488736	(bans hartley hartleys Hart Harts dit dits)

Units of Information Rate

Name	Quantity	Factor	Abbreviation(s)
bits-per-second	Rate	(/ bit second)	(bps)
bytes-per-second	Rate	(/ byte second)	(Bps)

Arithmetic Operations with Units

The with-units library contains procedures for arithmetic operations on quantities with units. A quantity with unit information is created by procedure val-with-units:

 (import unitconv with-units)
 (val-with-units 10 m) ->  #(10 #(unit meter (m meters) [Length] 1.0))

The following operations are available for operations on quantities with units:

• u:value: Returns the value of the given quantity.
• u:units: Returns the unit of the given quantity.
• u:equal?: Returns true if the units of the given quantities are equal, false otherwise.
• u:zero?
• u:=
• u:negate
• u:invert
• u:+ u:- u:* u:/
• u:sqrt
• u:sin
• u:cos
• u:expt

Version history

• 4.0 : Using exact arithmetic [André Sá]
• 3.3 : Additional units of time [André Sá]
• 3.0 : Compatibility with CHICKEN 5
• 2.6 : Bugfixes in unit* and unit/
• 2.3 : Added definitions for centimeter and centimeter-squared
• 2.2 : Removed redundant definition of define-unit (reported by felix)
• 2.1 : Documentation converted to wiki format
• 2.0 : Added unit arithmetic (with-units)
• 1.8 : Exporting all prefixed units; added info on information units [Joshua Griffith]
• 1.7 : Exporting the Rate quantity
• 1.6 : Exporting the IEC standard prefixes
• 1.5 : Ported to Chicken 4
• 1.4 : The predefined quantities have been put into unit-definitions.scm
• 1.3 : Bug fix in unit-convert
• 1.2 : Changed unit-convert to return a single numeric value given a single conversion argument
• 1.1 : Added information units [patch by Joshua Griffith]
• 1.0 : Initial release

License

Copyright 2007-2020 Ivan Raikov, André Sá.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A full copy of the GPL license can be found at http://www.gnu.org/licenses/.