swarmflow op• Data kinds: none → table (an op determined by its arguments alone — it takes no image or data input)
• Call: import fullseye as fs; fs.ledger.swarm_simulate(obstacle=None, speed: 'float' = 1.0, box=(8.0, 5.0), spacing: 'float' = 0.15, h_factor: 'float' = 1.3, tau: 'float' = 0.1, c: 'float' = 10.0, alpha: 'float' = 0.5, t_warm: 'float' = 2.0, n_frames: 'int' = 20, frame_dt: 'float' = 0.06, noise: 'float' = 0.0, seed: 'int' = 0) -> 'dict' (to call the implementation directly, import swarmflow; swarmflow.swarm_simulate(obstacle=None, speed: 'float' = 1.0, box=(8.0, 5.0), spacing: 'float' = 0.15, h_factor: 'float' = 1.3, tau: 'float' = 0.1, c: 'float' = 10.0, alpha: 'float' = 0.5, t_warm: 'float' = 2.0, n_frames: 'int' = 20, frame_dt: 'float' = 0.06, noise: 'float' = 0.0, seed: 'int' = 0) -> 'dict'; from the registry, opsdrive.get("swarm_simulate"))
A swarm (individuals moving as a weakly compressible SPH fluid) flowing through a periodic channel with obstacles. Obstacles act on the individuals only as "walls to bump into".
Acceleration of individual i = (U e_x − v_i)/τ (return to the free-stream speed) − Σ_j m (p_i/ρ_i² + p_j/ρ_j²) ∇W_ij (pressure = pushing against each other) − Σ_j m Π_ij ∇W_ij (Monaghan artificial viscosity, only for approaching pairs) + fluctuation (white noise with standard deviation noise [m/s²]).
Wall: an individual that has entered the inside of the circle is moved back to the surface and only its inward velocity is removed (slip wall). Periodic boundaries (both x and y). Integration is symplectic Euler, step is CFL 0.25 h/(c + U). When U τ ≪ R and c ≫ U, the steady flow is close to the potential flow around a cylinder (derivation in the module docstring).
Args:
obstacle: (xc, yc, R) [m] or None (no obstacle).
speed: free-stream speed U [m/s].
box: channel size (Lx, Ly) [m], centred at the origin.
spacing: initial lattice spacing [m] (spacing between individuals).
h_factor: h = h_factor × spacing.
tau: time constant for returning to the speed [s].
c: speed of sound [m/s] (stiffness of the pushing).
alpha: artificial viscosity coefficient.
t_warm: time to run before recording [s] (to approach steady state).
n_frames: number of frames to record (≥ 2).
frame_dt: frame interval [s].
noise: fluctuation of acceleration [m/s²].
seed: random seed.
Returns:
dict: frames (T, N, 2) positions [m] (already wrapped into the box), velocities (T, N, 2), t (T,), box,
obstacle, h, dt, rho0, density_range (1-99 % points of ρ/ρ₀ during recording), n_agents,
t_total (time run), t_wake_reenters (time at which the cavity behind the obstacle starts to wrap around from the right edge of the box to the left edge,
(Lx/2 − x_c − R)/U. Running longer than this lets cavity individuals enter at the upstream edge and contaminates the free stream).
★Behind the obstacle a long cavity extends that individuals do not enter (the pushing pressure is so weak that it does not pull, and the individuals only return to U by drag, so it is not filled from the sides). In the overhead video, the "hole" at the obstacle and the cavity itself are visible —— the claim of estimating from velocity alone means that the estimate does not use this hole (it is discarded as missing data in the velocity field), not that the video contains no cue of the obstacle.
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• The canonical algorithm (author, year) and its uses are named in the family usage guide above.
• poc_swarm_obstacle_from_flow — py -3.11 examples/poc_swarm_obstacle_from_flow.py
table as input)course_layout · course_occupancy · course_contains · world_build · world_camera · world_move · lidar_scan · rss_longitudinal_same
swarmflow)sph_kernel · sph_density_pressure · swarm_render_overhead · swarm_field_from_tracks · swarm_field_from_piv · potential_flow_cylinder · velocity_deficit_map · stagnation_from_centerline
*Provenance: swarmflow.py — DRIVE operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.