Home  Docs  GitHub  npm  Changelog  YouTube  Dimensional analysis and unit conversions
dimensional can be installed from the official npm package repository. It is highly recommended to install the latest version, which is installed by default with the following command.
npm i dimensional@0.4.1
Is there a way we can make dimensional better? Please report all bugs, issues, and new feature requests to the issues page in the official repository. For critical security issues, please send an email to dimensional@nicfv.com.
Thank you for your interest in contributing to dimensional! dimensional is an open source software package maintained by Nicolas Ventura (@nicfv) and built by users like you! You are allowed to fork the repository as permitted by the MIT License terms. Contributions are welcome by submitting a pull request. Please follow the existing code styling if submitting a pull request. Thank you for your consideration!
This package is currently under development and is not yet stable.
It will contain 3 main features:
 Dimensional analysis
 Quantity mathematics
 Unit conversions
How is the data structured? Remember the acronym "QUAD"! Math is performed primarily using quantities, which is the outermost structure. Let's say you have a quantity of \(5 [kN]\), for instance.

Quantity (5) [What is the value of measurement?]

Unit (kN) [What is the unit of measurement?]

Attribute (force) [What is being measured?]
 Dimension (\(\frac{\textbf{ML}}{\textbf{T}^{2}}\)) [What are the base dimensions?]

Attribute (force) [What is being measured?]

Unit (kN) [What is the unit of measurement?]
Here are a few quickstart examples written in JavaScript that showcase some outofbox features of the dimensional
package.
One day, you step onto a scale to determine your weight. It reads the number 150. What is this number? It is the force you are applying on to the scale. Europeans would be terrified to see this number, but Americans wouldn't even think twice. See, in the United States, scales read out units of pounds where in Europe, it would read out units of kilograms. What would a European scale say your weight is?
Now, here's an interesting predicament  pounds are units of force whereas kilograms are units of mass, which are completely different dimensions. In reality, a European scale is also measuring the force you apply, but in a different unit, called Newtons.
It just so happens that pounds are also units of mass, and on Earth, one pound of force equals one pound of mass. We'll get to this later.
So now that we know a European scale is actually measuring Newtons, what value would that be for \(150 [lb]\)? Based on results from plugging it into an online conversion calculator, I expect to see around \(667 [N]\). Let's see if it checks out.
 Copy the source code
 Paste into a new file
 Save as
UseTheForce.mjs
 Run this command in your terminal
node UseTheForce.mjs
import { Q, U } from 'dimensional';
// Weight is actually a force  not a mass!
// Therefore, units must be in pounds of force
const weight_lbs = Q(150, U({ pound_force: 1 }));
// We can easily obtain our weight in Newtons
// with a simple conversion using Quantity.as(unit)
const weight_N = weight_lbs.as(U({ Newton: 1 }));
// Print out the results of the conversion
console.log(weight_lbs.toString() + '=' + weight_N.toString());
// In case we want the raw value...
const weight_N_value = weight_N.value;
console.log('Raw value = ' + weight_N_value);
150 \left[\text{lb}_{f}\right]=667.2331370397568 \left[\text{N}\right]
Raw value = 667.2331370397568
Great, our first example checks out! But like I mentioned, European scales don't actually read out in Newtons, but in kilograms. Remember the relationship between force and mass from your physics class?
$$F=ma$$
$$\text{Force}=\text{mass}\times\text{acceleration}$$
We know the value of force and want to solve for mass. What would the acceleration be? This is the acceleration due to Earth's gravity. A good way to visualize that number is drop something (light weight, be safe!) and watch it fall. Notice how it speeds up as it falls  the "speed up" is the acceleration. We call this value \(g\). On Earth, \(g\approx 9.81 [m/s^{2}]\) in SI units.
$$m=\frac{F}{g}$$
We could convert \(g\) to US units, but there's no need, since dimensional
will handle all unit conversions internally.
When we divide force by acceleration, the units from force and acceleration will persist. We'll end up with a rather strange unit like this:
$$\frac{lb_{f}}{\frac{m}{s^{2}}}=\frac{lb_{f}s^{2}}{m}$$
What are the dimensions on this unit? We can run a quick dimensional analysis using Quantity.Unit.Attribute.Dimension.toString()
to get a humanreadable representation of our physical base dimensions. Believe it or not, the dimension of that unit is just mass! That means, we can convert quantities with that unit to any unit of mass.
From plugging it into an online calculator, I expect the result to be about \(68 [kg]\).
 Copy the source code
 Paste into a new file
 Save as
QuantityMath.mjs
 Run this command in your terminal
node QuantityMath.mjs
import { Q, U } from 'dimensional';
// This is our weight from the previous example
const weight_lbs = Q(150, U({ pound_force: 1 }));
// Define Earth's gravity at sea level in SI units
const gravity = Q(9.81, U({ meter: 1, second: 2 }));
// Remember `F=ma`? Rearrange to `m=F/a`
const mass = weight_lbs.over(gravity);
// The units persist through the operation, unless if they cancel
// So we'll get `lbf*s^2/m` ... which is not the most useful unit
console.log(mass.toString());
// What are the dimensions on this weird unit?
console.log('dim=' + mass.unit.attribute.dimension.toString());
// We can use the Quantity.as(unit) method to convert to kg
console.log(mass.as(U({ kilogram: 1 })).toString());
15.29051987767584 \left[\frac{\text{lb}_{f} \cdot \text{s}^{2}}{\text{m}}\right]
dim=\textbf{M}
68.01561029966939 \left[\text{k} \text{g}\right]