Reynolds Boids (Separation / Alignment / Cohesion)

Math essence

Toroidal pairwise distances via diff - dim*round(diff/dim). Per boid: sep_desired = mean(diff/(d^2 + eps)) over sep-neighbours; ali_desired = mean(velocity) over ali-neighbours; coh_desired = centroid(positions) - position over coh-neighbours. steer = limit(desired - vel, max_force). vel += weighted_sum(steers); vel = limit(vel, max_speed); pos = (pos + vel) mod dim. Canvas blending: canvas[p] = (1 - alpha) * canvas[p] + alpha * ink.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/shiffman_pearson_textbook/boidsClassic/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


class BoidsClassic:
    """Reynolds boids flocking (separation, alignment, cohesion).

    Implements the three classic Reynolds 1987 steering rules on a population
    of N point-boids with position and velocity:

    - **separation**: steer away from neighbours within ``sep_radius``
      (weighted inversely with distance).
    - **alignment**: steer toward the average heading of neighbours within
      ``ali_radius``.
    - **cohesion**: steer toward the centroid of neighbours within
      ``coh_radius``.

    Each rule produces a *desired* velocity; the steering force is the
    difference between desired and current velocity, capped at ``max_force``.
    Acceleration is integrated with explicit Euler, velocities are clamped to
    ``max_speed``, and the canvas wraps toroidally. Boids draw a short fading
    trail of their previous positions. This is the canonical Nature of Code /
    Coding Train / Generative Art formulation.

    Parameters
    ----------
    dim : int
        Square canvas side length (torus topology).
    num_boids : int
        Population size. Default 150 per Reynolds' original.
    perception_r : float
        Default radius for cohesion and alignment; separation uses its own.
    sep_radius, ali_radius, coh_radius : float | None
        Per-rule radii (default to ``perception_r`` if None).
    sep_weight, ali_weight, coh_weight : float
        Mixing weights for the three steering rules.
    max_speed, max_force : float
        Velocity and steering clamps.
    trail_alpha : float
        Per-segment trail fade.
    """

    family: ClassVar[str] = "shiffman_pearson_textbook"
    sketch: ClassVar[str] = "boidsClassic"

    def __init__(
        self,
        dim: int = 480,
        num_boids: int = 150,
        perception_r: float = 50.0,
        sep_radius: float | None = 24.0,
        ali_radius: float | None = 50.0,
        coh_radius: float | None = 50.0,
        sep_weight: float = 1.5,
        ali_weight: float = 1.0,
        coh_weight: float = 1.0,
        max_speed: float = 3.5,