pyLEAFS.population module

Forager populations.

A Population is a struct-of-arrays bag of agent bodies sharing a Grid. Each agent has a position, a unit heading, a fuel reserve, and some bookkeeping. The v1 controller is greedy and lives in the agent body: steer toward the nearest resource within sensing range, otherwise move ballistically with rotational diffusion.

The struct-of-arrays layout (parallel arrays rather than per-agent objects) keeps the step vectorizable and dimension-agnostic, and is the natural target for a later Numba pass. The Controller split (greedy vs. RNN) is reserved for a later layer; for now step calls the built-in greedy steering.

class pyLEAFS.population.Population(grid, v, dt, r_collect, R_sense, mu0, s_max, sigma=0.1, tau_A=1.0, repro_fraction=0.8, capacity=256)

Bases: object

A single-species greedy forager population (struct-of-arrays).

Parameters:

• grid (Grid) – Shared spatial grid.

• v (float) – Translational speed.

• dt (float) – Timestep.

• r_collect (float) – Collection radius; resources within this distance are harvested.

• R_sense (float) – Sensing radius; only resources within this distance steer the agent.

• mu0 (float) – Basal metabolic rate (fuel burned per unit time).

• s_max (float) – Maximum fuel reserve.

• sigma (float, optional) – Rotational-diffusion noise strength (default 0.1).

• tau_A (float, optional) – Heading persistence timescale (default 1.0).

• repro_fraction (float, optional) – Fuel threshold for budding, as a fraction of s_max (default 0.8).

• capacity (int, optional) – Initial array capacity; grows automatically as needed (default 256).

count

Number of live agents.

Type:

int

pos

Agent positions (a live view; copy if you need to retain it).

Type:

ndarray, shape (count, D)

heading

Unit heading vectors.

Type:

ndarray, shape (count, D)

fuel

Fuel reserves.

Type:

ndarray, shape (count,)

age

Age in timesteps.

Type:

ndarray, shape (count,)

ids

Stable unique id per agent (survives compaction).

Type:

ndarray, shape (count,)

harvested

Lifetime resources collected per agent.

Type:

ndarray, shape (count,)

offspring

Number of daughters budded per agent.

Type:

ndarray, shape (count,)

add(pos, heading=None, fuel=None, rng=None)

Add one agent. Returns its stable id.

Parameters:

• pos (array_like, shape (D,)) – Physical position (wrapped into the domain).

• heading (array_like, shape (D,), optional) – Heading vector (normalised); random if omitted (requires rng).

• fuel (float, optional) – Initial fuel; defaults to s_max.

• rng (numpy.random.Generator, optional) – Random source, used when heading is omitted.

index_of(agent_id)

Return the current array index of agent_id, or None if dead.

seed(n, rng, fuel=None)

Add n agents at uniformly random positions and headings.

step(fields, rng)

Advance every agent one timestep against the field list.

Greedy steering, motion, harvesting against the first ResourceField in fields, metabolism, budding, and death. Returns nothing; mutates the population in place.