mathjs/docs/datatypes/units.md

Units

Math.js supports units. Units can be used to do calculations and to perform conversions.

Usage

Units can be created using the function math.unit. This function accepts either a single string argument containing a value and unit, or two arguments, the first being a numeric value and the second a string containing a unit. Most units support prefixes like k or kilo, and many units have both a full name and an abbreviation. The returned object is a Unit.

Syntax:

math.unit(value: number, name: string) : Unit
math.unit(unit: string) : Unit
math.unit(unit: Unit) : Unit

Example usage:

const a = math.unit(45, 'cm')             // Unit 450 mm
const b = math.unit('0.1 kilogram')       // Unit 100 gram
const c = math.unit('2 inch')             // Unit 2 inch
const d = math.unit('90 km/h')            // Unit 90 km/h
const e = math.unit('101325 kg/(m s^2)')  // Unit 101325 kg / (m s^2)

const d = c.to('cm')                      // Unit 5.08 cm
b.toNumber('gram')                        // Number 100
math.number(b, 'gram')                    // Number 100

c.equals(a)                               // false
c.equals(d)                               // true
c.equalBase(a)                            // true
c.equalBase(b)                            // false

d.toString()                              // String "5.08 cm"

Use care when creating a unit with multiple terms in the denominator. Implicit multiplication has the same operator precedence as explicit multiplication and division, which means these three expressions are identical:

// These three are identical
const correct1 = math.unit('8.314 m^3 Pa / mol / K')          // Unit 8.314 (m^3 Pa) / (mol K)
const correct2 = math.unit('8.314 (m^3 Pa) / (mol K)')        // Unit 8.314 (m^3 Pa) / (mol K)
const correct3 = math.unit('8.314 (m^3 * Pa) / (mol * K)')    // Unit 8.314 (m^3 Pa) / (mol K)

But this expression, which omits the second / between mol and K, results in the wrong value:

// Missing the second '/' between 'mol' and 'K'
const incorrect = math.unit('8.314 m^3 Pa / mol K')           // Unit 8.314 (m^3 Pa K) / mol

Calculations

The operations that support units are add, subtract, multiply, divide, pow, abs, sqrt, square, cube, and sign. Trigonometric functions like cos are also supported when the argument is an angle.

const a = math.unit(45, 'cm')       // Unit 450 mm
const b = math.unit('0.1m')         // Unit 100 mm
math.add(a, b)                      // Unit 0.65 m
math.multiply(b, 2)                 // Unit 200 mm

const c = math.unit(45, 'deg')      // Unit 45 deg
math.cos(c)                         // Number 0.7071067811865476

// Kinetic energy of average sedan on highway
const d = math.unit('80 mi/h')      // Unit 80 mi/h
const e = math.unit('2 tonne')      // Unit 2 tonne
const f = math.multiply(0.5, math.multipy(math.pow(d, 2), e))
                                    // 1.2790064742399996 MJ

Operations with arrays are supported too:

// Force on a charged particle moving through a magnetic field
const B = math.evaluate('[1, 0, 0] T')         // [1 T, 0 T, 0 T]
const v = math.evaluate('[0, 1, 0] m/s')       // [0 m / s, 1 m / s, 0 m / s]
const q = math.evaluate('1 C')                 // 1 C

const F = math.multiply(q, math.cross(v, B))   // [0 N, 0 N, -1 N]

All arithmetic operators act on the value of the unit as it is represented in SI units. This may lead to surprising behavior when working with temperature scales like celsius (or degC) and fahrenheit (or degF). In general you should avoid calculations using celsius and fahrenheit. Rather, use kelvin (or K) and rankine (or degR) instead. This example highlights some problems when using celsius and fahrenheit in calculations:

const T_14F = math.unit('14 degF')            // Unit 14 degF (263.15 K)
const T_28F = math.multiply(T1, 2)            // Unit 487.67 degF (526.3 K), not 28 degF

const Tnegative = math.unit(-13, 'degF')      // Unit -13 degF (248.15 K)
const Tpositive = math.abs(T1)                // Unit -13 degF (248.15 K), not 13 degF

const Trate1 = math.evaluate('5 (degC/hour)') // Unit 5 degC/hour
const Trate2 = math.evaluate('(5 degC)/hour') // Unit 278.15 degC/hour

The expression parser supports units too. This is described in the section about units on the page Syntax.

User-Defined Units

You can add your own units to Math.js using the math.createUnit function. The following example defines a new unit furlong, then uses the user-defined unit in a calculation:

math.createUnit('furlong', '220 yards') 
math.evaluate('1 mile to furlong')            // 8 furlong

If you cannot express the new unit in terms of any existing unit, then the second argument can be omitted. In this case, a new base unit is created:

// A 'foo' cannot be expressed in terms of any other unit.
math.createUnit('foo') 
math.evaluate('8 foo * 4 feet')               // 32 foo feet

The second argument to createUnit can also be a configuration object consisting of the following properties:

• definition A string or Unit which defines the user-defined unit in terms of existing built-in or user-defined units. If omitted, a new base unit is created.
• prefixes A string indicating which prefixes math.js should use with the new unit. Possible values are 'none', 'short', 'long', 'binary_short', or 'binary_long'. Default is 'none'.
• offset A value applied when converting to the unit. This is very helpful for temperature scales that do not share a zero with the absolute temperature scale. For example, if we were defining fahrenheit for the first time, we would use: math.createUnit('fahrenheit', {definition: '0.555556 kelvin', offset: 459.67})
• aliases An array of strings to alias the new unit. Example: math.createUnit('knot', {definition: '0.514444 m/s', aliases: ['knots', 'kt', 'kts']})
• baseName A string that specifies the name of the new dimension in case one needs to be created. Every unit in math.js has a dimension: length, time, velocity, etc. If the unit's definition doesn't match any existing dimension, or it is a new base unit, then createUnit will create a new dimension with the name baseName and assign it to the new unit. The default is to append '_STUFF' to the unit's name. If the unit already matches an existing dimension, this option has no effect.

An optional options object can also be supplied as the last argument to createUnits. Currently only the override option is supported:

// Redefine the mile (would not be the first time in history)
math.createUnit('mile', '1609.347218694 m', {override: true})

Base units created without specifying a definition cannot be overridden.

Create several units at once

Multiple units can defined using a single call to createUnit by passing an object map as the first argument, where each key in the object is the name of a new unit and the value is either a string defining the unit, or an object with the configuration properties listed above. If the value is an empty string or an object lacking a definition property, a new base unit is created.

For example:

math.createUnit( {
  foo: {
    prefixes: 'long',
    baseName: 'essence-of-foo'
  },
  bar: '40 foo',
  baz: {
    definition: '1 bar/hour',
    prefixes: 'long'
  }
},
{
  override: true
})
math.evaluate('50000 kilofoo/s')  // 4.5 gigabaz

Return Value

createUnit returns the created unit, or, when multiple units are created, the last unit created. Since createUnit is also compatible with the expression parser, this allows you to do things like this:

math.evaluate('45 mile/hour to createUnit("knot", "0.514444m/s")')
// 39.103964668651976 knot

Support of custom characters in unit names

Per default, the name of a new unit:

• should start by a latin (A-Z or a-z) character
• should contain only numeric (0-9) or latin characters

It is possible to allow the usage of special characters (such as Greek alphabet, cyrillic alphabet, any Unicode symbols, etc.) by overriding the Unit.isValidAlpha static method. For example:

const isAlphaOriginal = math.Unit.isValidAlpha
const isGreekLowercaseChar = function (c) {
  const charCode = c.charCodeAt(0)
  return charCode > 944 && charCode < 970
}
math.Unit.isValidAlpha = function (c) {
  return isAlphaOriginal(c) || isGreekLowercaseChar(c)
}

math.createUnit('θ', '1 rad')
math.evaluate('1θ + 3 deg').toNumber('deg') // 60.29577951308232

API

A Unit object contains the following functions:

unit.clone()

Clone the unit, returns a new unit with the same parameters.

unit.equalBase(unit)

Test whether a unit has the same base as an other unit: length, mass, etc.

unit.equals(unit)

Test whether a unit equals an other unit. Units are equal when they have the same base and same value when normalized to SI units.

unit.format([options])

Get a string representation of the unit. The function will determine the best fitting prefix for the unit. See the Format page for available options.

unit.fromJSON(json)

Revive a unit from a JSON object. Accepts An object {mathjs: 'Unit', value: number, unit: string, fixPrefix: boolean}, where the property mathjs and fixPrefix are optional. Used when deserializing a unit, see Serialization.

unit.splitUnit(parts)

Split a unit into the specified parts. For example:

const u = math.unit(1, 'm')
u.splitUnit(['ft', 'in'])    // 3 feet,3.3700787401574765 inch

unit.to(unitName)

Convert the unit to a specific unit name. Returns a clone of the unit with a fixed prefix and unit.

unit.toJSON()

Returns a JSON representation of the unit, with signature {mathjs: 'Unit', value: number, unit: string, fixPrefix: boolean}. Used when serializing a unit, see Serialization.

unit.toNumber(unitName)

Get the value of a unit when converted to the specified unit (a unit with optional prefix but without value). The type of the returned value is always number.

unit.toNumeric(unitName)

Get the value of a unit when converted to the specified unit (a unit with optional prefix but without value). The type of the returned value depends on how the unit was created and can be number, Fraction, or BigNumber.

unit.toSI()

Returns a clone of a unit represented in SI units. Works with units with or without a value.

unit.toString()

Get a string representation of the unit. The function will determine the best fitting prefix for the unit.

unit.valType()

Get the string name of the current type of the value of this Unit object, e.g. 'number', 'BigNumber', etc.

Unit reference

This section lists all available units, prefixes, and physical constants. These can be used via the Unit object, or via math.evaluate().

Reference

Math.js comes with the following built-in units.

Base	Unit
Length	meter (m), inch (in), foot (ft), yard (yd), mile (mi), link (li), rod (rd), chain (ch), angstrom, mil
Surface area	m2, sqin, sqft, sqyd, sqmi, sqrd, sqch, sqmil, acre, hectare
Volume	m3, litre (l, L, lt, liter), cc, cuin, cuft, cuyd, teaspoon, tablespoon
Liquid volume	minim (min), fluiddram (fldr), fluidounce (floz), gill (gi), cup (cp), pint (pt), quart (qt), gallon (gal), beerbarrel (bbl), oilbarrel (obl), hogshead, drop (gtt)
Angles	rad (radian), deg (degree), grad (gradian), cycle, arcsec (arcsecond), arcmin (arcminute)
Time	second (s, secs, seconds), minute (mins, minutes), hour (h, hr, hrs, hours), day (days), week (weeks), month (months), year (years), decade (decades), century (centuries), millennium (millennia)
Frequency	hertz (Hz)
Mass	gram(g), tonne, ton, grain (gr), dram (dr), ounce (oz), poundmass (lbm, lb, lbs), hundredweight (cwt), stick, stone
Electric current	ampere (A)
Temperature	kelvin (K), celsius (degC), fahrenheit (degF), rankine (degR)
Amount of substance	mole (mol)
Luminous intensity	candela (cd)
Force	newton (N), dyne (dyn), poundforce (lbf), kip
Energy	joule (J), erg, Wh, BTU, electronvolt (eV)
Power	watt (W), hp
Pressure	Pa, psi, atm, torr, bar, mmHg, mmH2O, cmH2O
Electricity and magnetism	ampere (A), coulomb (C), watt (W), volt (V), ohm, farad (F), weber (Wb), tesla (T), henry (H), siemens (S), electronvolt (eV)
Binary	bits (b), bytes (B)

Note: all time units are based on the Julian year, with one month being 1/12th of a Julian year, a year being one Julian year, a decade being 10 Julian years, a century being 100, and a millennium being 1000.

Note that all relevant units can also be written in plural form, for example 5 meters instead of 5 meter or 10 seconds instead of 10 second.

Surface and volume units can alternatively be expressed in terms of length units raised to a power, for example 100 in^2 instead of 100 sqin.

Prefixes

The following decimal prefixes are available.

Name	Abbreviation	Value
deca	da	1e1
hecto	h	1e2
kilo	k	1e3
mega	M	1e6
giga	G	1e9
tera	T	1e12
peta	P	1e15
exa	E	1e18
zetta	Z	1e21
yotta	Y	1e24

Name	Abbreviation	Value
deci	d	1e-1
centi	c	1e-2
milli	m	1e-3
micro	u	1e-6
nano	n	1e-9
pico	p	1e-12
femto	f	1e-15
atto	a	1e-18
zepto	z	1e-21
yocto	y	1e-24

The following binary prefixes are available. They can be used with units bits (b) and bytes (B).

Name	Abbreviation	Value
kibi	Ki	1024
mebi	Mi	1024^2
gibi	Gi	1024^3
tebi	Ti	1024^4
pebi	Pi	1024^5
exi	Ei	1024^6
zebi	Zi	1024^7
yobi	Yi	1024^8

Name	Abbreviation	Value
kilo	k	1e3
mega	M	1e6
giga	G	1e9
tera	T	1e12
peta	P	1e15
exa	E	1e18
zetta	Z	1e21
yotta	Y	1e24

Physical Constants

Math.js includes the following physical constants. See Wikipedia for more information.

Universal constants

Name	Symbol	Value	Unit
speedOfLight	c	299792458	m · s-1
gravitationConstant	G	6.6738480e-11	m3 · kg-1 · s-2
planckConstant	h	6.626069311e-34	J · s
reducedPlanckConstant	h	1.05457172647e-34	J · s

Electromagnetic constants

Name	Symbol	Value	Unit
magneticConstant	μ0	1.2566370614e-6	N · A-2
electricConstant	ε0	8.854187817e-12	F · m-1
vacuumImpedance	Z0	376.730313461	Ω
coulomb	κ	8.9875517873681764e9	N · m2 · C-2
elementaryCharge	e	1.60217656535e-19	C
bohrMagneton	μB	9.2740096820e-24	J · T-1
conductanceQuantum	G0	7.748091734625e-5	S
inverseConductanceQuantum	G0-1	12906.403721742	Ω
magneticFluxQuantum	f0	2.06783375846e-15	Wb
nuclearMagneton	μN	5.0507835311e-27	J · T-1
klitzing	RK	25812.807443484	Ω

Atomic and nuclear constants

Name	Symbol	Value	Unit
bohrRadius	a0	5.291772109217e-11	m
classicalElectronRadius	re	2.817940326727e-15	m
electronMass	me	9.1093829140e-31	kg
fermiCoupling	GF	1.1663645e-5	GeV-2
fineStructure	α	7.297352569824e-3	-
hartreeEnergy	Eh	4.3597443419e-18	J
protonMass	mp	1.67262177774e-27	kg
deuteronMass	md	3.3435830926e-27	kg
neutronMass	mn	1.6749271613e-27	kg
quantumOfCirculation	h / (2me)	3.636947552024e-4	m2 · s-1
rydberg	R∞	10973731.56853955	m-1
thomsonCrossSection		6.65245873413e-29	m2
weakMixingAngle		0.222321	-
efimovFactor		22.7	-

Physico-chemical constants

Name	Symbol	Value	Unit
atomicMass	mu	1.66053892173e-27	kg
avogadro	NA	6.0221412927e23	mol-1
boltzmann	k	1.380648813e-23	J · K-1
faraday	F	96485.336521	C · mol-1
firstRadiation	c1	3.7417715317e-16	W · m2
loschmidt	n0	2.686780524e25	m-3
gasConstant	R	8.314462175	J · K-1 · mol-1
molarPlanckConstant	NA · h	3.990312717628e-10	J · s · mol-1
molarVolume	Vm	2.241396820e-10	m3 · mol-1
sackurTetrode		-1.164870823	-
secondRadiation	c2	1.438777013e-2	m · K
stefanBoltzmann	σ	5.67037321e-8	W · m-2 · K-4
wienDisplacement	b	2.897772126e-3	m · K

Note that the values of loschmidt and molarVolume are at T = 273.15 K and p = 101.325 kPa. The value of sackurTetrode is at T = 1 K and p = 101.325 kPa.

Adopted values

Name	Symbol	Value	Unit
molarMass	Mu	1e-3	kg · mol-1
molarMassC12	M(12C)	1.2e-2	kg · mol-1
gravity	gn	9.80665	m · s-2
atm	atm	101325	Pa

Natural units

Name	Symbol	Value	Unit
planckLength	lP	1.61619997e-35	m
planckMass	mP	2.1765113e-8	kg
planckTime	tP	5.3910632e-44	s
planckCharge	qP	1.87554595641e-18	C
planckTemperature	TP	1.41683385e+32	K