17 KiB
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:
var a = math.unit(45, 'cm'); // Unit 450 mm
var b = math.unit('0.1 kilogram'); // Unit 100 gram
var c = math.unit('2 inch'); // Unit 2 inch
var d = math.unit('90 km/h'); // Unit 90 km/h
var e = math.unit('101325 kg/(m s^2)'); // Unit 101325 kg / (m s^2)
var a = math.unit(55, 'cm'); // Unit 550 mm
var b = math.unit('0.1 kilogram'); // Unit 100 gram
var c = math.unit('2 inch'); // Unit 100 millimeter
var 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
var correct1 = math.unit('8.314 m^3 Pa / mol / K'); // Unit 8.314 (m^3 Pa) / (mol K)
var correct2 = math.unit('8.314 (m^3 Pa) / (mol K)'); // Unit 8.314 (m^3 Pa) / (mol K)
var 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'
var 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.
var a = math.unit(45, 'cm'); // Unit 450 mm
var b = math.unit('0.1m'); // Unit 100 mm
math.add(a, b); // Unit 0.65 m
math.multiply(b, 2); // Unit 200 mm
var c = math.unit(45, 'deg'); // Unit 45 deg
math.cos(c); // Number 0.7071067811865476
// Kinetic energy of average sedan on highway
var d = math.unit('80 mi/h') // Unit 80 mi/h
var e = math.unit('2 tonne') // Unit 2 tonne
var 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
var B = math.eval('[1, 0, 0] T'); // [1 T, 0 T, 0 T]
var v = math.eval('[0, 1, 0] m/s'); // [0 m / s, 1 m / s, 0 m / s]
var q = math.eval('1 C'); // 1 C
var 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 R) instead.
This example highlights some problems when using celsius and fahrenheit in calculations:
var T_14F = math.unit('14 degF'); // Unit 14 degF (263.15 K)
var T_28F = math.multiply(T1, 2); // Unit 487.67 degF (526.3 K), not 28 degF
var Tnegative = math.unit(-13, 'degF'); // Unit -13 degF (248.15 K)
var Tpositive = math.abs(T1); // Unit -13 degF (248.15 K), not 13 degF
var Trate1 = math.eval('5 (degC/hour)'); // Unit 5 degC/hour
var Trate2 = math.eval('(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.
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([precision])
Get a string representation of the unit. The function will determine the best fitting prefix for the unit. If precision is defined, the units value will be rounded to the provided number of digits.
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.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.toString()
Get a string representation of the unit. The function will determine the best fitting prefix for the unit.
Unit reference
This section lists all available units, prefixes, and physical constants. These can be used via the Unit object, or via math.eval().
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 | bit (b), byte (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 bit (b) and byte (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 |