Skip to content

program.md

Latest commit

 

History

History
69 lines (57 loc) · 3.79 KB

program.md

File metadata and controls

69 lines (57 loc) · 3.79 KB
Raw

Classic Performance Optimization

Objective

Maximize boid count at 60 FPS (browser-measured, clustered steady state). The evaluate command launches a browser, ramps boids, and reports max_boids.

The Loop

  1. Read shader.wgsl and simulation.js
  2. Pick ONE optimization for the flock_radius function (or supporting code)
  3. Edit the file(s)
  4. VALIDATE before committing:
    • Run: PATH=$HOME/.deno/bin:$PATH deno eval --unstable-webgpu "const a=await navigator.gpu.requestAdapter();const d=await a.requestDevice();const m=d.createShaderModule({code:await Deno.readTextFile('shader.wgsl')});const i=await m.getCompilationInfo();if(i.messages.length>0){console.log('SHADER ERROR');Deno.exit(1)}console.log('OK');d.destroy()"
    • If it prints SHADER ERROR: undo your edit and try something else. Do NOT commit broken code.
  5. git add shader.wgsl simulation.js && git commit -m "experiment: <description>"
  6. Run: python3 evaluate.py 2>/dev/null
  7. Parse the last line for max_boids: NNNNN
  8. If the result is 0 or contains "error": the experiment BROKE something. git revert --no-edit HEAD immediately.
  9. If max_boids improves over previous best -> KEEP, append result to results_classic_perf.tsv
  10. If max_boids does not improve -> git revert --no-edit HEAD, append result to results_classic_perf.tsv
  11. After reverting, verify the app still works by running the validate command from step 4.
  12. REPEAT. Do NOT pause. Loop until interrupted.

What You Can Edit

  • shader.wgsl
  • simulation.js

Focus on the flock_radius compute kernel in shader.wgsl (and pipeline/grid config in simulation.js if it is editable).

LOCKED - DO NOT MODIFY

The flock function in shader.wgsl is LOCKED. Do NOT change it in any way. Do NOT rename, rewrite, reorder, or touch any line inside flock.

What You CANNOT Edit

  • bench_browser.js, evaluate.py, render.wgsl, renderer.js, index.html
  • dashboard.py, serve.py, program.md, scheduler.py, schedule_config.json
  • Do NOT add roost attractors or global orbit forces

CRITICAL: Use git revert --no-edit HEAD to undo. NOT git reset --hard.

Results go in results_classic_perf.tsv

Constraints

  • flock_radius must produce correct flocking (separation, alignment, cohesion)
  • Boid struct: 64 bytes (16 floats) -- don't change the layout
  • Billboard additive + radius neighbor mode is what's benchmarked
  • Do NOT modify flock under any circumstances

LOCKED values in simulation.js — DO NOT CHANGE

If you edit simulation.js, these lines MUST remain exactly as they are:

  • Grid formula: Math.cbrt(numBoids / 4) — do NOT change to /8 or any other value
  • Visual range clamp: cellSize * 1.4 — do NOT change to 0.8 or any other value
  • Frame scheduling: odd frames drift, even frames full flock — do NOT add mod128 or other skip patterns
  • Auto-range stats: if (autoRangeEnabled && — do NOT disable with if (false &&

MANDATORY: Flocking Correctness Checks

Before committing ANY experiment, verify these are preserved:

  1. Heading update: boids_dst[i].heading MUST be written with a smoothly tracked direction based on velocity. Without this, boids face the wrong way.
  2. size_factor copy: boids_dst[i].size_factor = boid.size_factor MUST be written.
  3. 27-cell neighbor search: The flock function MUST search neighboring grid cells (3x3x3), not just the own cell. Own-cell-only breaks flocking.
  4. Separation + Alignment + Cohesion: All three forces must be computed. Removing any one breaks the flocking behavior.
  5. If a drift() pass exists: It MUST copy heading, size_factor, and all viz metrics (speed, neighbor_count, etc.) from src to dst.

If you remove any of these for performance, the experiment WILL be reverted because the visual result will be broken even if the benchmark passes.