unitconv

Description

Conversion of units of measurement.

Usage

(require-extension unitconv)

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:procedure

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?:procedure

Returns true if the two units have the same dimension and factor, false otherwise.

(define-quantity name expr)syntax

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)syntax

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)syntax

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

NameQuantityFactorAbbreviation(s)
yoctoUnity1e-24
zeptoUnity1e-21
attoUnity1e-18
femtoUnity1e-15
picoUnity1e-12
nanoUnity1e-09
microUnity1e-06
milliUnity0.001
centiUnity0.01
deciUnity0.1
decaUnity10.0
hectoUnity100.0
kiloUnity1000.0
megaUnity1000000.0
gigaUnity1000000000.0
teraUnity1000000000000.0
petaUnity1e+15
exaUnity1e+18
zettaUnity1e+21
yottaUnity1e+24

IEC Standard Prefixes

NameQuantityFactorAbbreviation(s)
kibiUnity1024
mebiUnity1048576
gibiUnity1073741824.0
tebiUnity1099511627776.0
pebiUnity1.12589990684262e+15
exbiUnity1.15292150460685e+18
zebiUnity1.18059162071741e+21
yobiUnity1.20892581961463e+24

Time Multiples

NameQuantityFactorAbbreviation(s)
twelveUnity12
sixtyUnity60

Angles

NameQuantityFactorAbbreviation(s)
NameQuantityFactorAbbreviation(s)
degreeUnity(/ pi 180)(deg degrees)

Units of Length

NameQuantityFactorAbbreviation(s)
meterLength1.0(m meters)
inchLength0.0254(in inches)
footLength0.3048(ft feet)
angstromLength1e-10(ang angstroms)
parsecLength3.083e+16(parsecs)

Units of Area and Volume

NameQuantityFactorAbbreviation(s)
square-meterArea(* meter meter)(m^2 m2 meter-squared meters-squared square-meters)
square-inchArea(* inch inch)(in^2 inch-squared inches-squared square-inches)
square-micronArea(* micrometer micrometer)(um^2 micrometer-squared micrometers-squared micron-squared microns-squared square-microns)
square-millimeterArea(* millimeter millimeter)(mm^2 millimeter-squared millimeters-squared square-millimeters)
cubic-meterVolume(* meter (* meter meter))(m^3 meter-cubed meters-cubed cubic-meters)
literVolume(* 0.001 cubic-meter)(L litre liters)

Units of Mass

NameQuantityFactorAbbreviation(s)
kilogramMass1.0(kg kilograms)
gramMass0.001(g grams)
poundMass(* gram 453.59237)(lb pounds)
slugMass(* pound 32.17405)(slugs)
atomic-mass-unitMass1.6605402e-27(amu atomic-mass-units)

Units of Time

NameQuantityFactorAbbreviation(s)
secondTime1.0(s seconds)
hourTime(* sixty (* sixty second))(h hrs hours)

Units of Acceleration

NameQuantityFactorAbbreviation(s)
meters-per-second-squaredAcceleration(/ meter (* second second))(m/s2 m/s^2 m/sec2 m/sec^2)

Units of Frequency

NameQuantityFactorAbbreviation(s)
hertzFrequency1.0(hz)

Units of Force

NameQuantityFactorAbbreviation(s)
newtonForce(/ (* kilogram meter) (* second second))(nt newtons)
pound-forceForce(/ (* slug foot) (* second second))(lbf)

Units of Power

NameQuantityFactorAbbreviation(s)
wattPower(/ (* kilogram meter meter) (* second second second))(W watts)
horsepowerPower(* 550 (/ (* foot pound-force) second))(hp)

Units of Energy

NameQuantityFactorAbbreviation(s)
jouleEnergy(* newton meter)(J joules)
electron-voltEnergy(* 1.60217733e-19 joule)(ev electron-volts)
kilowatt-hourEnergy(* kilo (* watt hour))(kwh kilowatt-hours)
calorieEnergy(* 4.184 joule)(cal calories)
ergEnergy(* 1e-07 joule)(ergs)
british-thermal-unitEnergy(* 1055.056 joule)(btu btus)

Units of Current

NameQuantityFactorAbbreviation(s)
ampereCurrent1.0(A amp amps amperes)

Units of Electric Charge

NameQuantityFactorAbbreviation(s)
coulombCharge(* ampere second)(C coulombs)

Units of Electric Potential

NameQuantityFactorAbbreviation(s)
voltPotential(/ (* kilogram meter meter) (* ampere second second second))(V volts)

Units of Resistance

NameQuantityFactorAbbreviation(s)
ohmResistance(/ volt ampere)(ohms)

Units of Capacitance

NameQuantityFactorAbbreviation(s)

Units of Conductance

NameQuantityFactorAbbreviation(s)
siemensConductance(/ ampere volt)(S mho)

Units of Inductance

NameQuantityFactorAbbreviation(s)
henryInductance(/ (* meter meter kilogram) (* ampere ampere second second))(H)

Units of Magnetic Flux

NameQuantityFactorAbbreviation(s)
teslaMagnetic-Flux-Density(/ kilogram (* ampere second second))(T teslas)
weberMagnetic-Flux(/ (* kilogram meter meter) (* ampere second second))(wb webers)

Units of Magnetic Field Strength

NameQuantityFactorAbbreviation(s)
ampere-per-meterMagnetic-Field-Strength(/ ampere meter)(amperes-per-meter)

Units of Substance

NameQuantityFactorAbbreviation(s)
moleSubstance1.0(mol moles)

Units of density

NameQuantityFactorAbbreviation(s)
rhoDensity(/ kilogram cubic-meter)

Units of concentration

NameQuantityFactorAbbreviation(s)
molarityConcentration(/ mole liter)(M mol/L)
parts-per-millionConcentration(/ milligram kilogram)(ppm)

Units of temperature

NameQuantityFactorAbbreviation(s)
degKTemperature1.0(K)

Units of information

NameQuantityFactorAbbreviation(s)
bitInformation1(b bits shannon shannons Sh)
byteInformation8(B bytes)
natInformation1.44269504088896(nats nit nits nepit nepits)
banInformation3.32192809488736(bans hartley hartleys Hart Harts dit dits)

Units of information rate

NameQuantityFactorAbbreviation(s)
bits-per-secondRate(/ bit second)(bps)
bytes-per-secondRate(/ 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

Ivan Raikov

Repository

https://github.com/iraikov/chicken-unitconv

Version history

4.0
Using exact arithmetic [André Sá]
3.3
Additional units of time [André Sá]
3.0
Ported to 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
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

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

This program is free software: you can redistribute it and/or modify