pqm

Physical Quantities and Measures (PQM)

PQM is a node.js and browser javascript library for dealing with numbers with units like "10 meters". With it you can create variables that represent these physical quantities and use them for math just like a normal numeric variable.

PQM is designed to be simple, lightweight and fast. In addition:

• It has no dependencies
• Provides definitions for nearly 200 common units, as well as providing the ability for the user to define their own
• The minified and zipped module is less than 6 kB
• Quantity objects have an optional strict unit definition that eliminates the possibility of "unit collisions" that plague many other libraries of this type
• Arrays are fully supported for more efficient processing
• Conversion factors are tested against conversions defined in Special Publication 811: NIST Guide to the SI

Developers

For the best experience developing pqm, install the following software first:

• Node JS
• NPM

The package requires a submodule, so clone from github as follows:

git clone --recurse-submodules https://github.com/GhostWrench/pqm.git

Install NPM development dependencies

npm install

After making changes to source build the package using the very simple build scripts.

Linux

./build.sh

Windows

.\build

You can test the package for node/browser and check coverage with the following commands (do this after you build):

npm test

npm run-script testbrowser

npm run-script coverage

Comparison to similar packages

Feature	pqm	js-quantities	convert-units	mathjs	unitmath
Overview
Version Tested	0.5.0	1.7.5	2.3.4	7.0.0	0.8.5
Number of Dependencies	0	0	2	8	1
Number of Dependents	0	39	143	984	0
Unpacked Size	136 kB	585 kB	106 kB	10.1 MB	522 kB
Minified & GZip Size	5.8 kB	8.8 kB	5.8 kB	152.0 kB	9.7 kB
Node (CommonJS)	Yes	Yes	Yes	Yes	Yes
Browser	Yes	Yes	No	Yes	Yes
ES Module	Yes	Yes	Yes	Yes	Yes
Support for Unit Prefixes	Yes	Yes	Limited	Yes	Yes
Number of Base Units Supported	193	187	61	162	135
Define Custom Units	Yes	No	No	Yes	Yes
Tracks input units	No	Yes	No	Yes	Yes
Support For Basic Math	Yes	Yes	No	Yes	Yes
Test Coverage	100%	Unknown	Unknown	Unknown	99%
Supported Operators
Add / Subtract	Yes	Yes	No	Yes	Yes
Multiply / Divide	Yes	Yes	No	Yes	Yes
Raise Power	Yes	No	No	Yes	Yes
Root	Yes	No	No	Yes	Yes
Comparison Operators	Yes	Yes	No	== only	Yes
Support for array operations	Yes	Convert Only	No	Yes	No
Benchmarks
Module load time	1.9 ms	4.5 ms	14.7 ms	366 ms	39.5 ms
Simple Conversion (mL -> gal)	0.60 ms	5.0 ms	0.27 ms	0.34 ms	0.40 ms
Compound Unit Conversion	0.75 ms	5.0 ms	N/A	0.44 ms	0.50 ms
Math Operations *	0.18 ms (8x)	1.15 ms (50x)	N/A	0.50 ms (22x)	0.55 ms (24x)
Math with Array(1000) *	4.4 ms (5x)	N/A	N/A	38.5 ms (30x)	N/A

* : Value in parenthesis is the multiple of the same operation using just floats

Installing and importing PQM

Installation

npm install pqm

Importing the module

PQM provides both ESM and CommonJS packages upon installation:

// ESM
import pqm from "pqm";

// CommonJS
var pqm = require("pqm");

If using PQM in a browser, the ESM module can be used directly:

<script src="path/to/pqm.js" type="module"></script>

Or a simple IIFE package can be found in build\iife\pqm.js.

Creation of Basic Quantity Variables

Create a basic quantity

Use the pqm.quantity constructor to create a physical quantity

let q = pqm.quantity(10, "m");

Create a quantity with compound units

By raising the power of the unit:

let q = pqm.quantity(10, "m^2");

By combining units:

let q = pqm.quantity(10, "g m^2");

By combining units with "/", all units after the division will be inverted, do not use parenthesis.

let q = pqm.quantity(10, "g m^2 / s^3");

The above is equivalent to the following expression using negative powers:

let q = pqm.quantity(10, "g m^2 s^-3");

Create a quantity with unit prefixes

Prefixes such as kilo (k) or micro (m) can be added to any unit. The preferred syntax for doing so is to enclose the prefix in brackets in front of the unit. For example:

let q = pqm.quantity(10, "[k]m / [m]s"); // 10 kilometers per millisecond

There are multiple reasons for this convention.

1. Using brackets will give your code a slight performance boost
2. You will completely avoid 'unit collision' where you might use the wrong unit on accident. Consider min (minute) vs. [m]in (milliinch)
3. Your units will be explicit and easy to read

Of course, if you would prefer not to use brackets, the quantity function will try to figure out what prefix-unit pair you meant by trial and error.

Here is the full list of unit collisions to be aware of

Unit Symbol	Returns	Does Not Return
ppt	ppt (Parts per Trillion)	[p]pt (pico-pint)
min	min (Minute)	[m]in (milli-inch)
nmi	nmi (Nautical Mile)	[n]mi (nano-mile)
Gs	Gs (Gauss)	[G]s (Giga-second)
PS	PS (Metric Horsepower)	[P]S (Peta-Siemens)
dword	dword (Double Word)	[d]word (deci-word)

Notes on quantity creation

This is a table of all units supported by PQM, use it as a reference for all the available units provided by this package. Be aware that unit names are case sensitive. For example a rad is a Radian and a RAD is a Radiation Absorbed Dose.

Convert quantities to a different unit of measure

The value of a quantity can be obtained in any equivalent unit using the in function.

let q = pqm.quantity(1, "[k]m");
q.in("m"); // 1000.0
q.in("ft"); // 3280.839895013123

While users are always encouraged to use the in function for conversion, there are other variants of this function that convert quantities to a human readable form that are easier to use. Namely:

Function	Attempts to convert the quantity to
inSI()	SI Base and derived unit representation
inCGS()	CGS (centimeter, gram second) unit representation
inUS()	US Customary unit representation
toString()	String in SI Unit systems

Because of the many different ways that units can be represented, these functions may not always give you an answer that is appropriate. But they are useful for troubleshooting and understanding what the current state of a quantity is, so they have been included in PQM. Also note that only inSI can represent any quantity. Other functions may throw errors if they cannot be used to fully represent the quantity.

Perform math operations on physical quantities

Adding and subtracting units which are dimensionally equivalent

let q1 = pqm.quantity(1, "m");
let q2 = pqm.quantity(10, "[c]m");

q1.add(q2).in("[c]m"); // 110
q1.sub(q2).in("[c]m"); // 90

Multiplying and dividing quantities with any other quantity or scalar

let q1 = pqm.quantity(10, "m / s");
let q1 = pqm.quantity(5, "s");

q1.mul(50).in("m / s"); // 500
q1.mul(q2).in("m"); // 50
q1.div(q2).in("m / s^2"); // 2

Raise quantities to an integer power

let q = pqm.quantity(1000, "m");
q.pow(2).in("[k]m^2"); // 1

Inverting a quantity

let q1 = pqm.quantity(10, "m");

q1.inv().in("1 / m"); // 0.1

Definition of Custom Physical Quantities

There are many units which are not included by default in the PQM module. Fortunately, users are allowed to define their own units. Take the following example that adds the "thermochemical" definitions of Calorie (cal) and British Thermal Unit (BTU) which differ slightly from the standard versions.

pqm.define("cal_th", 4.184, "J"); // By definition
pqm.define("BTU_th", 1, "cal_th deltaF lbm / deltaC g");

console.log(pqm.quantity(1, "BTU").in("J")); // 1055.05585262
console.log(pqm.quantity(1, "BTU_th").in("J")); // 1054.3502644888652

Comparisons of Quantities

The following table describes the various comparison operators available

Function	Operation
eq	Equal ==
lt	Less than <
lte	Less than or equal <=
gt	Greater than >
gte	Greater than or equal >=

Each of these operators takes another quantity and a tolerance. The tolerance determines how close in magnitude two quantities can be to be considered equal. This tolerance can be provided as another compatible quantity, or as a percent of the left (calling) quantity. If a tolerance is not provided, 0 percent will be assumed. For example:

let q1 = pqm.quantity(1000, "[m]m / s");
let q2 = pqm.quantity(1001, "[m]m / s");
let q3 = pqm.quantity(1003, "[m]m / s");
let absoluteTolerance = pqm.quantity(2, "[m]m / s");

q1.eq(q2) // false
q1.eq(q2, absoluteTolerance); // = true
q1.lt(q2, absoluteTolerance); // = false
q1.lt(q3, absoluteTolerance); // = true
q1.eq(q2, 1e-6); // = false
q1.eq(q2, 1e-2); // = true

More comparison examples

let q1 = pqm.quantity(10, "m");
let q2 = pqm.quantity(10, "m^2");

q1.eq(q2); // error
q1.pow(2).eq(q2); // false
q1.pow(2).gt(q2); // true
q1.pow(2).div(10).eq(q2, 1e-6); // true

Note on temperatures and other units with zero offsets

There are a few temperature and pressure units that have zero offsets. This means that 0 is not the same in these units as it is in the SI base unit (Kelvin, "K"). The two most widely used of these units are degC (Degrees Celsius) and degF (Degrees Fahrenheit). These units are limited in what operations can be done to them. There are also two complimentary units deltaC and deltaF that represent changes in temperature that do not have these restrictions, but do not convert the way it is normally expected that these units convert. The table below gives the available operations for each type of unit.

Operation	deg unit behavior	Example
in	Can be converted to any compatible unit	0 degC -> 32 degF
add	Allowed, but only with delta unit	10 degC + 10 deltaC -> 20 degC
sub	Allowed, subtracting a delta unit will preserve the zero offset, subtracting a zero offset unit will create a new delta unit	20 degC - 10 deltaC -> 10 degC 20 degC - 10 degC -> 10 deltaC
mul	Allowed only with unit-less quantity	10 degC * 10 -> 100 degC
div	Allowed only with unit-less quantity	10 degC / 2 -> 5 degC
inv	Not allowed
pow	Not allowed
Comparison operators (eq, lt, lte, gt, gte)	Allowed, but only with absolute tolerances	10 degC > 32 degF -> true

It is recommended that the use of deg units be for simple conversions and that if more advanced math or compound units are needed, use the delta version of the units. However, be careful, as they may not convert as expected:

let zeroDeltaC = pqm.quantity(0, "deltaC");
let someDeltaF = pqm.quantity(32, "deltaF");
let absoluteZero = pqm.quantity(0, "K");

zeroDeltaC.eq(absoluteZero); // = true
zeroDeltaC.eq(someDeltaF); // = false

let freezingDegC = pqm.quantity(0, "degC");

freezingDegC.in("deltaC"); // = 273.15

Using arrays

Full support for arrays is available, when crunching large amounts of data, it is much more efficient to use quantity arrays. A quantity array can be created the same way a normal quantity is created using the quantity constructor:

let qarr1 = pqm.quantity([1,2,3], "m / s^2");
let qarr2 = pqm.quantity([1,4,3], "m / s^2");

Array quantities can use all of the same functionality as scalar quantitites but the in, inSI and comparison functions like eq will return an array rather than a number or boolean value.

qarr1.in("[k]m / s^2"); // [1e-3, 2e-3, 3e-3]
qarr1.eq(qarr2); // [true, false, true]

Operations such as add, sub, mul operate slightly differently depending on their inputs.

1. For two array of the same length, the operation is done element-wise
2. For a scalar (or length 1 array) with an array, the scalar is applied through the full array.

For example:

qarr1.add(qarr2).in("m / s^2"); // [2, 6, 6]
let scalar = pqm.quantity(2, "[k]g");
let len1 = pqm.quantity([2], "m");
scalar.mul(qarr1).in("N"); // [2, 4, 6]
qarr1.div(len1).in("1 / s^2"); // [0.5, 1, 1.5]

Finally, note that any operation with an array will result in an array value, even if the array is of length one. This may necessitate a change in the calling code if it is expecting a number instead of an array.

scalar.in("g"); // 1000
scalar.mul(len1).in("g m"); // [1000]

Table of available units

Link

Table of available unit prefixes

Prefix symbol	Name	Modifying Value
y	yocto	1e-24
z	zepto	1e-21
a	atto	1e-18
f	femto	1e-15
p	pico	1e-12
n	nano	1e-9
u	micro	1e-6
m	milli	1e-3
c	centi	1e-2
d	deci	1e-1
da	deca	1e1
h	hecto	1e2
k	kilo	1e3
M	mega	1e6
G	giga	1e9
T	tera	1e12
P	peta	1e15
E	exa	1e18
Z	zetta	1e21
Y	yotta	1e24
Ki	kibi	2^10
Mi	mebi	2^20
Gi	gibi	2^30
Ti	tebi	2^40
Pi	pebi	2^50
Ei	exbi	2^60
Zi	zebi	2^70
Yi	yobi	2^80