Social foraging: protocol and measurement record

This page records the current experimental questions and estimators for social foraging. It is a protocol page, not a findings page: the repository contains registered implementations, but no complete promoted result packet currently supports a numerical or mechanistic conclusion here.

Evidence status

A runnable experiment is not automatically a published result. Numerical claims should be added only from a complete, immutable packet with a DONE marker, resolved conditions, raw paired-seed rows, provenance, declared estimands, and the analysis that produced the reported uncertainty. Scratch runs and a directory that still contains RUNNING do not meet that standard.

Questions the current designs can address

The registered protocols separate four questions that are easy to conflate:

1. Total social-information contrast: under otherwise matched conditions, does enabling the conspecific receptor bank change task-relative outcomes compared with zeroing that bank?
2. Bearing-information contrast: does the real conspecific bearing pattern differ from a per-agent permutation of the same bank values across bearing bins?
3. Search-cost contrast: at a declared horizon, how does the restricted time-to-source cost of the social controller compare with the asocial controller and a random-output reference?
4. Descriptive organization: how do polarization, milling, and cohesion change across those conditions?

The fourth question is descriptive. These protocols do not by themselves establish recruitment, information transmission through a particular contact, a causal mechanism, a percolation transition, or collective criticality.

Task and common setup

Agents forage on a periodic square arena with one fixed source. Source information is local: agents receive it only within source_vision_range. The main protocols use 48 agents, 100 nodes per reservoir, a 12-by-12 arena, matched motors, physical coupling off, and paired seeds. The complete resolved values belong in each result packet’s manifest.toml; the values named here are orientation, not a substitute for that manifest.

The task score is mean proximity over the recorded window:

$$\mathrm{forage\_score} = \operatorname{clamp}\!\left(1 - \overline{d_\mathrm{source}}/(L/\sqrt{2}),\ 0,\ 1\right).$$

It is a task-relative proximity score, not a first-passage time or an unrestricted search rate. Use reach_and_mfpt for arrival outcomes and retain its censoring information.

This single rollout is useful for checking configuration and rendering. It is not evidence for a condition effect:

using BrainlessLab

sim = simulate(:forage;
    node=:falandays_oosawa,
    n_agents=48,
    n_nodes=100,
    space_size=12.0,
    source_position=(6.0, 6.0),
    vision_range=4.0,
    source_vision_range=0.8,
    sens_agent_dist=1,
    norm_mode=:divisive,
    norm_sigma=1.0,
    conspecific_gain=4.0,
    source_gain=2.0,
    noise_gain=0.25,
    motor=KinematicMotor(top_speed=0.1),
    visual_coupling=true,
    conspecific_vision=true,
    physical_coupling=false,
    capture_radius=1.0,
    ticks=3000,
    seed=1,
    record=(:poses,))

(score=sim.metrics.forage_score, reach=reach_and_mfpt(sim))

Protocol 1: horizon-restricted search efficiency

Source: experiments/search_efficiency.jl

This protocol runs three matched conditions for each seed:

condition	controller	source sensing	conspecific sensing	role
maxent	:null_random	configured identically	off	random-output reference
asocial	:falandays_oosawa	on	off	controller without social input
social	:falandays_oosawa	on	on	controller with social input

The implementation verifies that initial agent positions match across all three conditions for a given seed. Agents spawned inside the capture radius are excluded from first-passage summaries. Agents that do not arrive by the horizon remain right-censored.

The primary cost is

$$\tau_H = E[\min(T_\mathrm{hit}, H)],$$

estimated from eligible-agent restricted costs. The reported search currencies are horizon-specific log-ratios, for example

$$K_H^\mathrm{social} = \log_{10}\!\left(\tau_H^\mathrm{maxent}/ \tau_H^\mathrm{social}\right), \qquad \Delta K_H = \log_{10}\!\left(\tau_H^\mathrm{asocial}/ \tau_H^\mathrm{social}\right).$$

Seeds, not agents, are the independent resampling clusters. mfpt_reached summarizes completers only and must not replace the restricted-cost estimand when censoring is present. A finite-horizon value should not be described as an unrestricted search efficiency unless censoring is negligible and that approximation is justified.

julia --project=. experiments/run.jl --list
julia -t auto --project=. experiments/run.jl search_efficiency seeds=0:99 ticks=10000 bootstrap=5000

The packet includes manifest.toml, per_seed.csv, per_agent.csv, summary.csv, conditions.csv, and explicit RUNNING/DONE state.

Protocol 2: distribution-matched sensory controls

Source: experiments/forage_intrinsic_drive_controls.jl

This protocol holds reservoir construction and receptor width constant while changing the conspecific bank:

condition	conspecific bank	estimand role
social	real bearing-bank values	structured social input
distribution_matched	each agent’s values permuted across bearing bins	bank activity without its original angular arrangement
blind	same bank slots zeroed	no conspecific-bank drive

The paired contrast social - blind is the total effect of exposing this controller to its social bank under the tested regime. social - distribution_matched tests sensitivity to the original angular arrangement while preserving bank values, active-bin count, and L2 energy. It does not prove that bearing information is the only changed statistical property over time.

The protocol screens a declared intrinsic-drive grid on one seed block, selects the cell with the smallest across-condition mean-score range, and evaluates that selection on a disjoint holdout seed block. Its paired intervals, sign-flip tests, Holm adjustment, omnibus label permutation, and equivalence rule apply only to the declared metrics and selected design.

julia -t auto --project=. experiments/run.jl forage_intrinsic_drive_controls

The default writes numerical/statistical outputs only. For representative media, first instantiate the pinned renderer and then opt in; the study checks it before any rollout:

julia --project=experiments/figures -e 'using Pkg; Pkg.instantiate()'
julia -t auto --project=. experiments/run.jl forage_intrinsic_drive_controls render=true

Do not interpret a partially written packet. In particular, the presence of screening output does not imply that holdout evaluation, figures, or inferential summaries completed.

Interpretation boundaries

• Pairing: preserve within-seed condition pairing. Agents within one seed are repeated units, not independent replicates.
• Selection: treat screening as selection, not confirmation. Inferential claims belong to the disjoint holdout phase.
• Censoring: report the horizon, eligible count, reached count, and censor fraction beside any arrival-time contrast.
• Metric scope: forage_score, reach fraction, restricted search cost, and collective organization measure different things. Agreement is empirical, not definitional.
• Generalization: the current protocols test one task geometry, controller family, motor, and hand-set operating regime. They do not establish a general property of social collectives.
• Mechanism: a condition contrast establishes an outcome difference under that intervention. It does not identify attraction, recruitment, signalling, or topology as the mediating process.

Evidence required for a findings section

A defensible findings section needs one coherent promoted packet containing:

• an explicit DONE state and no unresolved failed cells;
• full git SHA, dirty/patch provenance, Julia and dependency versions, resolved parameters, and exact seed blocks;
• raw per-seed paired outcomes and per-agent rows where those support the estimand;
• predeclared primary contrasts, censoring treatment, selection rule, and multiplicity handling;
• uncertainty over independent seeds, with discovery and holdout phases kept separate;
• robustness checks that change at least the seed block, horizon, and relevant task/controller settings; and
• language limited to the measured contrast unless a separate mediation or topology design tests the proposed mechanism.

Until such a packet is promoted, this page should remain a precise account of what the experiments ask and how their outputs must be read.