This project is part of the @thi.ng/umbrella monorepo.

• About
  • Unit definitions
  • Predefined units
    • Acceleration
    • Angle
    • Area
    • Data
    • Electric current
    • Energy
    • Force
    • Frequency
    • Length
    • Luminous intensity
    • Mass
    • Parts per notation
    • Power
    • Pressure
    • Speed
    • Substance
    • Temperature
    • Time
    • Volume
  • Creating & deriving units
    • Using standard metric prefixes
    • Unit combinators
  • Unit conversions
• Status
• Installation
• Dependencies
• API
• Authors
• License

About

Extensible SI unit creation, conversions & calculations (~150 units predefined).

All unit definitions & conversions are based on the SI unit system & concepts described here:

• https://en.wikipedia.org/wiki/International_System_of_Units
• https://en.wikipedia.org/wiki/SI_base_unit
• https://en.wikipedia.org/wiki/SI_derived_unit
• https://en.wikipedia.org/wiki/Coherence_(units_of_measurement)
• https://en.wikipedia.org/wiki/Metric_prefix

Unit definitions

Each unit is defined via a 7-dimensional vector representing individual exponents for each of the SI base unit dimensions, in order:

Dimensionless units (e.g. radian, byte) are supported too and represented by a vector with all dimensions set to zero.

Additionally, we also define a scale factor and zero offset for each unit, with most dimensions' base units usually using a factor of 1 and no offset.

For example, here's how we can define kilograms and meters:

// kilogram, SI dimension 0
const KG = coherent(1);
// { dim: [ 1, 0, 0, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: true }

// meters, SI dimension 1
const M = coherent(1);
// { dim: [ 0, 1, 0, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: true }

// kelvin, SI dimension 4 (here without syntax sugar)
const K = unit(4, 1, 0, true);
// { dim: [ 0, 0, 0, 0, 1, 0, 0 ], scale: 1, offset: 0, coherent: true }

// fahrenheit, SI dim 4 with custom scale factor and zero offset
const F = unit(4, 1 / 1.8, 459.67 / 1.8);
// { dim: [ 0, 0, 0, 0, 1, 0, 0 ],  scale: 0.5555, offset: 255.3722, coherent: false }

More complex units like electrical resistance (e.g. ohm) are based on more than a single dimension:

// ohm = volt / ampere
div(V, A)
// { dim: [ 1, 2, -3, -2, 0, 0,  0 ], scale: 1, offset: 0, coherent: true }

This dimension vector represents the unit definition for (see SI derived units):

Ω = kg⋅m²⋅s⁻³⋅A⁻²

Btw. The formatSI() function can be used to format a unit's dimension vector:

formatSI(div(V, A));
// "kg·m2·s-3·A-2"

Predefined units

The following units are provided as "builtins", here grouped by dimension:

Acceleration

Angle

Area

Data

Electric current

Energy

Force

Frequency

Length

Luminous intensity

Mass

Parts per notation

https://en.wikipedia.org/wiki/Parts-per_notation

Power

Pressure

Speed

Substance

Temperature

Time

Volume

Creating & deriving units

Using standard metric prefixes

Existing coherent units can be prefixed to produce derived versions:

// define micrometer (also available as preset)
prefix("µ", "m")
// { dim: [ 0, 1, 0, 0, 0, 0, 0 ], scale: 0.000001, offset: 0, coherent: false }

// define kKhz
prefix("k", Hz);
// { dim: [ 0, 0, -1, 0, 0, 0, 0 ], scale: 1000, offset: 0, coherent: false }

Unit combinators

The following combinators can be used to derive scaled and/or more complex units in multiple SI dimensions:

• div(a, b): derives a new unit via the division of the given units
• mul(a, b): derives a new unit as the product of the given units
• pow(u, k): raises given unit to power k (e.g. meter ⇒ square meter)
• reciprocal(u): Creates reciprocal of given unit (e.g. Hz ⇒ 1/second)

// acceleration (meter per second squared)
const m_s2 = div(m, pow(s, 2));
// { dim: [ 0, 1, -2, 0, 0, 0,  0 ], scale: 1, offset: 0, coherent: false }

// define kilowatt-hour (also available as preset)
const kWh = mul(prefix("k","W"), "h");
// { dim: [ 1, 2, -2, 0, 0, 0, 0 ], scale: 3600000, offset: 0, coherent: false }

// define `word` as 16 bits
const word = mul(bit, 16);
// { dim: [ 0, 0, 0, 0, 0, 0, 0 ], scale: 16, offset: 0, coherent: false }

// Hz = 1/s
const Hz = reciprocal(s);
// { dim: [ 0, 0, -1, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: false }

Unit conversions

Only units with compatible (incl. reciprocal) dimensions can be converted, otherwise an error will be thrown. All dimensionless units can be converted to other dimensionless units (even if it would be semantic nonsense).

Units can be specified in various ways:

// convert from km/h to mph using unit names
convert(100, "km/h", "mph");
// 62.13711922373341

// or using predefined unit constants directly
convert(60, mph, km_h);
// 96.56063999999998

// or using anonymous units (meter/second ⇒ yard/hour)
convert(1, "m/s", div(yd, h));
// 3937.007874015749

// convert into opposite direction (meter/second  ⇒ second/meter)
convert(10, "m/s", reciprocal("m/s"));
// 0.1

Another example using dimensionless units (here angles, arc second ⇒ radian) to compute the distance of 10 arcsec on the earth surface (in meters):

const R = 6371000; // earth radius in meters

convert(10, "arcsec", "rad") * R;
// 308.87479623488537

Status

BETA - possibly breaking changes forthcoming

Search or submit any issues for this package

Installation

yarn add @thi.ng/units

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/units"></script>

Skypack documentation

For Node.js REPL:

const units = await import("@thi.ng/units");

Package sizes (brotli'd, pre-treeshake): ESM: 3.57 KB

Dependencies

• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/errors

API

Generated API docs

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-units,
  title = "@thi.ng/units",
  author = "Karsten Schmidt",
  note = "https://thi.ng/units",
  year = 2021
}

License

© 2021 - 2023 Karsten Schmidt // Apache License 2.0