Tutorial: Dimensional Analysis and SI Units

In this tutorial you will learn to work with physical quantities using Ninbot’s dimensional analysis system. You will see how to create quantities with different dimensions, perform arithmetic that respects dimensional rules, and convert between different units of the same dimension.

The Setup

Physical quantities have dimensions (length, time, mass, etc.) and units (metres, seconds, kilograms, etc.). Ninbot enforces dimensional analysis: you cannot add a length to a time, but you can multiply them to get velocity. The library uses SI (International System of Units) as the canonical representation.

The Code

#include <print>
import ninbot;

int main()
{
   using namespace nin::units;

   length   distance = 100_m;
   nin::time duration = 5_s;
   mass     weight   = 75_kg;

   std::println("Distance: {}", distance);
   std::println("Duration: {}", duration);
   std::println("Mass: {}", weight);


   length a = 3_m;
   length b = 4_m;
   length sum = a + b;
   length diff = b - a;

   std::println("\n{} + {} = {}", a, b, sum);
   std::println("{} - {} = {}", b, a, diff);
   std::println("Are they equal? {}", a == 3_m);


   length   side = 5_m;
   area     square_area = side * side;

   std::println("\nArea of {0}×{0} square: {1}", side, square_area);

   length   distance_m = 100_m;
   nin::time duration_s = 10_s;
   velocity speed = distance_m / duration_s;

   std::println("Speed: {}", speed);

   acceleration gravity = 9.81_m / (1_s * 1_s);
   std::println("Gravitational acceleration: {}", gravity);

   force weight_force = weight * gravity;
   std::println("Weight force: {}", weight_force);


   length   meters = 1_km;
   std::println("\n1 km = {}", meters);
   std::println("1 km = {}", metres(1000));
   std::println("1 km = {:_cm}", meters);

   std::println("\nPhysical constants:");
   std::println("Speed of light: {}", nin::constants::c);

   return 0;
}

Output

Distance: 100 (m)
Duration: 5 (s)
Mass: 75 (kg)

3 (m) + 4 (m) = 7 (m)
4 (m) - 3 (m) = 1 (m)
Are they equal? true

Area of 5 (m)×5 (m) square: 25 (m²)
Speed: 10 (m/s)
Gravitational acceleration: 9.81 (m/s²)
Weight force: 735.75 (kg⋅m/s²)

1 km = 1000 (m)
1 km = 1000 (m)
1 km = 100000 (cm)

Physical constants:
Speed of light: 299792458 (m/s)

Building the code

Save the example as units.c++ alongside this CMakeLists.txt:

cmake_minimum_required(VERSION 4.0)
project(units LANGUAGES CXX)

find_package(Ninbot REQUIRED)

add_executable(units units.c++)
target_link_libraries(units PRIVATE ninbot::ninbot)

Then configure and build:

cmake -B build -G Ninja -DCMAKE_PREFIX_PATH=/path/to/ninbot/build
cmake --build build
./build/units

Walkthrough

Imports and namespaces

#include <print>
import ninbot;

The ninbot.pos module provides everything needed, including the units system.

using namespace nin::units;

This brings the units and quantity definitions into scope.

Basic SI quantities

length    distance = 100_m;
nin::time duration = 5_s;
mass      weight   = 75_kg;

Ninbot defines type aliases for common quantities: length, time, mass, velocity, acceleration, force, etc.

The _m, _s, _kg suffixes are unit literals that create quantities with the appropriate dimension and value.

Arithmetic with quantities

length a = 3_m;
length b = 4_m;
length sum = a + b;
length diff = b - a;

Quantities with the same dimension can be added, subtracted, and compared. The result has the same dimension as the operands.

std::println("Are they equal? {}", a == 3_m);

Equality comparison works as expected.

Dimensional analysis: multiplication and division

length   side = 5_m;
area     square_area = side * side;

Multiplying two lengths produces an area. Ninbot automatically computes the resulting dimension by adding exponents: length × length = length².

length    distance_m = 100_m;
nin::time duration_s = 10_s;
velocity  speed = distance_m / duration_s;

Dividing a length by a time produces a velocity. The dimension is computed by subtracting exponents: length¹ / time¹ = length¹⋅time⁻¹ (velocity).

acceleration gravity = 9.81_m / (1_s * 1_s);

Acceleration is velocity per unit time: length / (time²).

force weight_force = weight * gravity;

Force is mass times acceleration: mass × acceleration = mass⋅length/time² (Newtons).

Unit conversion

Different units represent the same dimension. Ninbot stores values internally in SI base units and provides conversion functions.

length   meters = 1_km;
std::println("1 km = {}", meters);

The variable meters holds 1000 metres (the SI representation of 1 kilometre). When printed, the value shows as 1000 (m).

std::println("1 km = {}", metres(1000));

metres() is an explicit unit function that constructs a length quantity from a numeric value in metres.

std::println("1 km = {:_cm}", meters);

The format specifier _cm converts the quantity to centimetres for display. The same value 1000 metres is printed as 100000 (cm).

Physical constants

std::println("Speed of light: {}", nin::constants::c);

Ninbot provides SI physical constants in the nin::constants namespace. The speed of light is defined as 299792458 m/s (the exact SI value).

Common constants available include: - c — speed of light in vacuum - G — gravitational constant - ℎ — Planck constant - k — Boltzmann constant - And many others following CODATA conventions