dimensional

Home | Docs | GitHub | npm | Changelog | YouTube | Dimensional analysis and unit conversions

Installation

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

Bugs and Requests

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 [e-mail].

Contribute

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!

Getting Started

This package is currently under development and is not yet stable.

It will contain 3 main features:

1. Dimensional analysis
2. Quantity mathematics
3. Unit conversions

Data Structure

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?]

Examples

Here are a few quickstart examples written in JavaScript that showcase some out-of-box features of the dimensional package.

Use The Force

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.

Instructions

1. Copy the source code
2. Paste into a new file
3. Save as Use-The-Force.mjs
4. Run this command in your terminal

   node Use-The-Force.mjs
   

Source

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);

Output

150 \left[\text{lb}_{f}\right]=667.2331370397568 \left[\text{N}\right]
Raw value = 667.2331370397568

Quantity Math

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 human-readable 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]\).

Instructions

1. Copy the source code
2. Paste into a new file
3. Save as Quantity-Math.mjs
4. Run this command in your terminal

   node Quantity-Math.mjs
   

Source

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());

Output

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]