Boids Flock (Hodgin Murmuration)

Math essence

For each boid i, accumulate weighted sums of separation (1/r^2 push inside separation_radius), alignment (mean velocity inside neighbor_radius), and cohesion (mean position inside neighbor_radius), using a uniform spatial hash for O(num) total work. A weak goal-toward-vector adds a small acceleration. Total acceleration is clamped to max_force, integrated into velocity (clamped to max_speed) and position. The previous-to-current position segment is stroked onto a decaying canvas.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/hodgin_iquilezles/BoidsFlock/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


class BoidsFlock:
    """Boids Flock — Robert Hodgin (flight404), circa 2003–2024.

    A 2D Reynolds-style boids simulation in the spirit of Hodgin's
    *Murmuration* / "Bird Migration" series (roberthodgin.com/project/murmuration).
    Each boid obeys three classic Reynolds rules — *separation*, *alignment*,
    *cohesion* — applied to all neighbours inside ``neighbor_radius``.
    A weak long-range "migration" force tugs the flock toward ``goal``,
    yielding the swooping, ever-coalescing silhouettes Hodgin is known for.

    Particles trace a low-alpha stroke from their previous to their current
    position; the accumulated frame buffer is the rendered image.  The
    algorithm uses a coarse spatial hash so that ~200–1000 boids run in
    near-realtime even on pure NumPy.
    """

    family: ClassVar[str] = "hodgin_iquilezles"
    sketch: ClassVar[str] = "boidsflock"

    def __init__(
        self,
        dim: int = 500,
        num: int = 250,
        neighbor_radius: float = 32.0,
        separation_radius: float = 14.0,
        w_sep: float = 1.6,
        w_align: float = 1.0,
        w_coh: float = 0.9,
        w_goal: float = 0.04,
        max_speed: float = 3.2,
        max_force: float = 0.18,
        trail_decay: float = 0.965,
        ink_color: tuple[int, int, int] = (240, 245, 255),
        background: tuple[int, int, int] = (8, 8, 14),
        **_,
    ) -> None:
        self.dim = dim
        self.num = num
        self.neighbor_radius = neighbor_radius
        self.separation_radius = separation_radius
        self.w_sep = w_sep
        self.w_align = w_align
        self.w_coh = w_coh
        self.w_goal = w_goal
        self.max_speed = max_speed
        self.max_force = max_force
        self.trail_decay = trail_decay
        self.ink_color = np.array(ink_color, dtype=np.float32)
        self.bg_color = np.array(background, dtype=np.float32)
        self.reset()

    def reset(self, seed: int | None = None) -> None:
        self.rng = np.random.default_rng(seed)