N150 N300 T3K P100 P150 P300C Galaxy 30 min Validated

Overview

Particle Life is an emergent complexity simulator where different particle species interact based on randomly generated attraction/repulsion rules. Simple physics creates unpredictable and beautiful patterns.

Features:

Why This Project:

Time: 30 minutes | Difficulty: Intermediate

Deploy the Project

📦 Deploy All Cookbook Projects

This creates the project in ~/tt-scratchpad/cookbook/particle_life/.

Example Output

Particle Life Simulation

500 frames of emergent patterns running on QuietBox (4x P300c). Red, green, and blue species interact based on randomly generated attraction/repulsion rules. Order emerges from chaos, then dissolves back into chaos. No two runs are ever the same.

View full animation →

Simulation details:

Running the Project

Quick start:

🌌 Run Particle Life Simulation
VS Code
cd ~/tt-scratchpad/cookbook/particle_life && export PYTHONPATH=~/tt-metal:$PYTHONPATH && python3 test_particle_life.py

Manual commands:

cd ~/tt-scratchpad/cookbook/particle_life

# Run simulation (creates particle_life.gif)
python test_particle_life.py

# Or run directly with custom parameters
python particle_life.py --num-particles 2048 --num-steps 500 --species 3

What you'll see:

Initializing Particle Life simulation...
✓ TT device opened
✓ 2,048 particles across 3 species
✓ Random attraction matrix generated

Simulating 500 steps...
Step 50/500... 100/500... 150/500... 200/500... 250/500... 300/500... 350/500... 400/500... 450/500... 500/500

Rendering animation...
✓ Animation saved to: particle_life.gif

Simulation complete!
- Total force calculations: 2,097,152,000
- Runtime: 192.8 seconds
- Performance: ~10.9 million calculations/second

The Science

Interaction Rules:

Each species pair has an attraction/repulsion value:

Example interaction matrix:

       Red    Green   Blue
Red    0.1    -0.5     0.3
Green  0.2     0.0    -0.4
Blue  -0.3     0.6     0.1

This means:

Emergent Behaviors:

From these simple rules, complex patterns emerge:

Extensions

1. More Species

Try 5-7 species for more complex interactions:

python particle_life.py --species 7

2. Larger Simulations

Scale up particle count:

python particle_life.py --num-particles 4096 --num-steps 300

3. Custom Interaction Rules

Modify the attraction matrix in particle_life.py to create specific behaviors:

# Predator-prey setup
interactions = np.array([
    [ 0.1, -0.8,  0.0],  # Predators repel each other, chase prey
    [ 0.6,  0.0, -0.5],  # Prey attract each other, flee predators
    [-0.3,  0.4,  0.2],  # Scavengers avoid predators, attracted to prey
])

4. Add Obstacles

Introduce boundary conditions or obstacles:

# Add walls
def apply_boundaries(positions):
    # Bounce off walls
    positions = np.clip(positions, 0.1, 0.9)
    return positions

5. 3D Particle Life

Extend to three dimensions:

# 3D positions and forces
positions_3d = np.random.rand(num_particles, 3)
# Calculate forces in 3D space

🚀 Bonus: Multi-Chip Acceleration (QuietBox Systems)

Unlock the full power of QuietBox with multi-device parallelization!

If you're running on a QuietBox system with multiple chips (4x P300c, 8x P150, etc.), you can accelerate the simulation by distributing the N² force calculations across all available devices.

The Multi-Device Implementation

The particle_life_multi_device.py script extends the original implementation with workload partitioning:

Strategy:

  1. Partition particles across devices (e.g., 512 particles per chip on 4-device system)
  2. Parallel computation: Each device computes forces for its particle subset against ALL particles
  3. Aggregate results: Forces from all devices are gathered and combined

Key Code Pattern:

# Open all available devices
devices = []
for device_id in range(num_devices):
    devices.append(ttnn.open_device(device_id=device_id))

# Create multi-device simulation
sim = ParticleLifeMultiDevice(
    devices=devices,  # List of device handles
    num_particles=2048,
    num_species=3
)

# Run with automatic parallelization
history = sim.simulate(num_steps=500)

Benchmark Results (4x P300c QuietBox)

Real-world performance on QuietBox Blackhole Tower:

Mode Runtime Performance Speedup
Single-device 4.8s ~87.9M calc/s 1.0x (baseline)
Multi-device (4 chips) 2.4s ~177.2M calc/s 2.0x

Parallel Efficiency: 50% (2x on 4 devices)

Running Multi-Device Mode

cd ~/tt-scratchpad/cookbook/particle_life

# Benchmark: Compare single vs multi-device
python test_multi_device.py

# Direct multi-device run
python particle_life_multi_device.py --multi-device

Why 50% Efficiency?

This is actually quite good for a CPU-based particle simulation! Efficiency is limited by:

  1. Data transfer overhead: Each device needs full particle positions to compute forces
  2. Aggregation cost: Results must be gathered from all devices each frame
  3. Workload granularity: 512 particles per device is relatively small

Improving Efficiency

Try these experiments to push toward 3-4x speedup:

# Larger workload (more particles per device)
python particle_life_multi_device.py --multi-device --num-particles 4096 --num-steps 300

# More species (more complex interactions)
python particle_life_multi_device.py --multi-device --species 7

# Longer simulation (amortize setup cost)
python particle_life_multi_device.py --multi-device --num-steps 1000

Advanced: On-Device Force Calculations

For maximum performance, move force calculations entirely to TT hardware using TTNN operations:

# Convert positions to TTNN tensors on device
positions_tt = ttnn.from_torch(positions, device=device, layout=ttnn.TILE_LAYOUT)

# Compute forces using TTNN ops (matrix operations on TT hardware)
forces_tt = compute_forces_ttnn(positions_tt)

# Synchronize results back to CPU only when needed
forces = ttnn.to_torch(forces_tt).cpu()

This approach could achieve near-linear scaling (3.5-4x on 4 devices) by eliminating CPU bottlenecks.

What You Accomplished

This demonstrates: Multi-chip workload distribution, performance benchmarking, and scaling efficiency analysis - essential skills for production deployments!

What You Learned

This recipe demonstrates: Going from tutorial concepts to novel creation. You learned the fundamentals in earlier recipes, now you're creating something completely original!

Learn More

Inspiration:

Related recipes:

Contribute:

What You Learned

Congratulations! You've completed all 5 cookbook recipes. Ready for more? Check out the Cookbook Overview for ideas on combining projects, or explore production models in the Advanced Topics section.