Strongly-typed physical quantities


Updated 8 Sep 2019

From GitHub

View License on GitHub

# PhysicalQuantity

I've always wondered why programming languages only implement the number sets used in mathematics—? (int8, uint64, etc.), ? (complex(), etc.), variations of ? (double, single, ,...), etc. To any physicist, it would make sense to have a data type that represents a physical quantity; something that has both a value (double) and a unit of measurement. Preferably, this datatype would behave intuitively for all sorts of standard operations - a Mass times a Length divided by a Time² should give a Force, according to Isaac Newton, yet that same set of operations can not ever equal an Area.

This submission is an implementation of such a datatype.


- put the PhysicalQuantity and PhysicalVectorQuantity directories on the
MATLAB search path, recursively

Example session:

>> L = Length(4, 'm')
L =
4 meters

>> R = Length(2, 'ft')
R =
2 feet

>> A = Area(L*R, 'm^2')
A =
2.4384e+00 square meters

Let's check: 1 ft = 0.3048 meter, so
2 ft * 4 m = 2*0.3048 * 4 = 2.4384 square meters. Cool!

Try the following:

>> A = Area(L*L*R, 'm^2')
Error using Area (line 13)
Can't create 'Area' (dimensions [L]²) from a quantity with dimensions [L]³.

>> A = Area(L*R, 'm^3')
Error using Area (line 13)
Dimensions implied by the given string ([L]³) are incompatible with those of an Area ([L]²).

>> tan( Area(L*R, 'm^2') )
Can't compute the tangent() of an Area.

Angles are dimensionless and are treated as special in this framework:

>> theta = Angle(-1.2, 'deg')
theta =
-1.2 degrees

>> cos(theta)
ans =
9.997806834748455e-01 % <- indeed the same as cosd(-1.2)

>> phi = Angle(0.5, 'rad')
phi =
500 milliradians

# Overview

In physics, a quantity's *unit* is intricately connected to the quantity itself. Typically, quantities with different units cannot be used in the same operation, without some sort of conversion between them - you can't "add apples to oranges".

This is not unlike data types in most programming languages. What do you expect to get when you divide two integers? Add a boolean to a character? You can't just do that without some sort of conversion.

Therefore, it makes sense to create a data type that takes physical units into consideration for all operations. Preferably, this data type is also super-easy to use, and produces intelligible error messages when it's used in a physically meaningless way.

And that is exactly what this tool set aims to provide.

# How to use

PysicalQuantities are constructed from scratch like this:

Q = <quantityname>(<value>, <units>)

Take a look in the PhysicalQuantity directory for an overview of currently
supported <quantities>. The <value> can be any numeric value (including
sparse, complex, etc.). The <units> should be a string specifying any of
the supported long/short unit names (see below), possibly prefixed with
an SI-multiplier (for metric units). Multiple units can be combined by the
following operations:

'*': multiply
'/': divide
'^': exponentiate


F = Force(300, 'Newton')
r = Density(2, 'kg/m^3')

To get a list of available units:

>> L = Length();
>> L.listUnits()
Length supports the following units of measurement:
- Chinese mile (li)
- Parsec (pc)
- astronomical unit (AU)
- foot (ft)
- furlong (fur)
- inch (in)
- lightyear (ly)
- meter (m)
- mile (mi)
- nautical mile (n.mi)
- smoot (smt)
- statute mile (st.mi)
- yard (yd)
- Ångström (Å)

Conversions between compatible units are seamless:

>> L = Length(20, 'yards');
>> L('meters')
ans =
1.8288e+01 meters

>> P = Length(3, 'inch');
>> Q = Length(18, 'foot');
>> Length( L*P/Q, 'meter' )
ans =
254 millimeters

Operations work as expected:

>> L = Length(1, 'inch');
>> t = Duration(32, 'seconds');
>> M = Mass(18, 'lb');
>> F = Force( M*L/t/t, 'Newton' )
ans =
2.025219058242187e+02 milliNewtons

# Note

If you observe something odd, please give me a heads up.
Preferably, raise an issue on GitHub :) Otherwise, plain ol'
email will do.

Cite As

Rody Oldenhuis (2023). PhysicalQuantity (, GitHub. Retrieved .

MATLAB Release Compatibility
Created with R2018b
Compatible with R2016b and later releases
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!










Versions that use the GitHub default branch cannot be downloaded

Version Published Release Notes

See release notes for this release on GitHub:


Updated tests, documentation and bumped version to > 0 (=ready for real-world use)


To view or report issues in this GitHub add-on, visit the GitHub Repository.
To view or report issues in this GitHub add-on, visit the GitHub Repository.