Skip to content

Your First Simulation

Now that you have Zigma running, let's write a real simulation.

We are going to calculate the position of an object in free fall. In traditional languages like Python or C++, you would just use raw numbers (floats) and hope you remembered which variable represents meters and which represents seconds.

In Zigma, we let the compiler do the tracking.

Step 1: Defining Physical Quantities

Create a new file named falling.zma and define our initial conditions. We attach units directly to our values:

g  = 9.81 m/s2   // Gravity
t  = 3 s         // Time
v0 = 0 m/s       // Initial downward velocity

Zigma understands that g is not just the number 9.81—it is a Tensor with the physical dimension of Acceleration (Length / Time²), mapped to the scale of meters per second squared.

Step 2: The Math

Now, let's write the standard kinematic equation for position: $y = v_0 t - \frac{1}{2} g t^2$.

y = (v0 * t) - (0.5 * g * t^2)

Behind the scenes, Zigma calculates the dimensions step-by-step at compile time:

  1. v0 * t multiplies [m/s] by [s], resulting in [m].
  2. t^2 squares the time, resulting in [s2].
  3. g * t^2 multiplies [m/s2] by [s2], resulting in [m].
  4. It subtracts [m] from [m], which is perfectly legal.

The variable y is now safely typed as [m] (Length).

Step 3: Printing and Converting

Let's print the result. Zigma automatically formats the output to include the correct unit. We can also ask Zigma to convert the velocity after 3 seconds into kilometers per hour using the in keyword.

print "Position: {y}"

// Calculate final velocity: v = v0 - g*t
v_final = v0 - (g * t)
v_final_kmh = v_final in km/h

print "Velocity: {v_final_kmh}"

Run the code using zigma falling.zma --run and you will see: 

Position: -44.145m
Velocity: -105.948km.h⁻¹

Step 4: The Magic (Compile-Time Safety)

Let's pretend we made a typo in our physics formula. Add this line to the bottom of your file:

// Trying to add Position [Length] and Time [Time]
wrong = y + t

Now try to run the script again (zigma falling.zma --run).

The program will refuse to compile and give you this.

error: adding [L] to [T]
 13 | wrong = y + t
               ^^^

Zigma's dimensional analysis engine detects that adding meters to seconds is physically impossible. Instead of letting your simulation crash in the middle of a 10-hour run or silently producing garbage data, Zigma stops you immediately.

Because this check happens entirely during the translation to Zig (at comptime), the final machine code contains zero overhead. By the time the program runs, the unit checks have already been erased, leaving only blazing-fast math.

Next Steps

You now know the core philosophy of Zigma: Write math, attach units, and trust the compiler.

Where to go next?