← Back to AILP Home

Dimensional Analysis User Guide

Overview

Dimensional Analysis in Nitpick is a compiler-enforced type safety mechanism that verifies equations according to the laws of physics. By associating physical units with deterministic types like fix256, the compiler ensures that operations are dimensionally consistent.

Motivation: Thermodynamic Constitutionalism

In complex physics simulations, robotics, and safety-critical systems (like the Nikola AGI consciousness substrate), category errors in equations can lead to catastrophic failures. Mixing dimensions (e.g., adding Energy to Time) corrupts manifold topology and violates fundamental thermodynamic laws.

Traditional languages allow mixing arbitrary numerical types, meaning dimensional correctness is entirely up to the programmer. Nitpick elevates dimensional correctness to the type system level, enforcing "Thermodynamic Constitutionalism" syntactically.

Syntax

Dimensional types are declared by parameterizing a base type with a registered Unit identifier enclosed in angle brackets:

fix256<Joules>:energy = 500.0fix256;
fix256<Meters>:distance = 10.0fix256;
fix256<Seconds>:time = 2.5fix256;

Available Base Units

Dimensional analysis is currently supported for the deterministic fix256 type.

Nitpick supports the standard SI base units and derived units. Internally, these are represented as a 7-component dimension vector: [Length, Mass, Time, Current, Temperature, Amount, Luminosity].

Unit Dimension Vector Represents
Meters [1, 0, 0, 0, 0, 0, 0] Length
Kilograms [0, 1, 0, 0, 0, 0, 0] Mass
Seconds [0, 0, 1, 0, 0, 0, 0] Time
Amperes [0, 0, 0, 1, 0, 0, 0] Electric Current
Kelvin [0, 0, 0, 0, 1, 0, 0] Temperature
Moles [0, 0, 0, 0, 0, 1, 0] Amount of substance
Candelas [0, 0, 0, 0, 0, 0, 1] Luminous Intensity

Derived Units: | Unit | Dimension Vector | Represents | |------|------------------|------------| | Newtons | [1, 1, -2, 0, 0, 0, 0] | Force | | Joules | [2, 1, -2, 0, 0, 0, 0] | Energy | | Watts | [2, 1, -3, 0, 0, 0, 0] | Power |

Arithmetic Rules

The compiler strictly enforces the following rules for dimensional arithmetic:

Addition and Subtraction

Values can only be added or subtracted if they share the exact same dimension.

fix256<Joules>:e1 = 100.0fix256;
fix256<Joules>:e2 = 50.0fix256;

// ✓ ALLOWED: Same dimension
fix256<Joules>:total = e1 + e2;

// ✗ FORBIDDEN: Dimension mismatch (Compile Error)
// fix256<?>:invalid = e1 + distance;

Multiplication

When multiplying two dimensional values, their dimension vectors are added together.

fix256<Newtons>:force = 10.0fix256;
fix256<Meters>:distance = 5.0fix256;

// ✓ ALLOWED: Force * Distance = Energy
// [1,1,-2...] + [1,0,0...] = [2,1,-2...] (Joules)
fix256<Joules>:work = force * distance;

Division

When dividing two dimensional values, the divisor's dimension vector is subtracted from the dividend's dimension vector.

fix256<Meters>:distance = 100.0fix256;
fix256<Seconds>:time = 5.0fix256;

// ✓ ALLOWED: Distance / Time = Velocity
// [1,0,0...] - [0,0,1...] = [1,0,-1...]
fix256<MetersPerSecond>:velocity = distance / time;

Scalar Operations

Operations involving dimensionless scalars leave the dimension unchanged.

fix256<Joules>:e1 = 100.0fix256;
fix256:scalar = 2.0fix256;

// ✓ ALLOWED: Scales the value, dimension remains Joules
fix256<Joules>:scaled = e1 * scalar;

Error Handling

Dimensional mismatches are caught at compile-time, preventing flawed physics code from ever executing.

Example Compile Error:

Error: Dimensional mismatch in addition.
Cannot add type 'fix256<Joules>' to type 'fix256<Seconds>'.

Examples

1. Velocity Calculation

fix256<Meters>:d = 100.0fix256;
fix256<Seconds>:t = 9.58fix256;
fix256<MetersPerSecond>:v = d / t;

2. Kinetic Energy (KE = ½mv²)

fix256<Kilograms>:mass = 50.0fix256;
fix256<MetersPerSecond>:velocity = 10.0fix256;
fix256:half = 0.5fix256;

// velocity * velocity = MetersSquaredPerSecondSquared
// mass * (v^2) = KilogramMetersSquaredPerSecondSquared = Joules
fix256<Joules>:ke = half * mass * (velocity * velocity);

Limitations