Sequences

The sequences module defines AMBER’s vectorized view API. The full population lives at model.agents; filtered and scatter views are produced by where / indexing / at[...]. All three view types share the same attribute/assignment protocol — column reads return Polars Series sourced from model.agents_df, and column writes queue through the batched flush path.

AgentList

class ambr.AgentList(model: Model, agents_or_n: List[Agent] | int = None, agent_type: Type[Agent] | None = None)

Bases: _BaseView

Full view over a model’s population. Lives at model.agents.

__getitem__(idx)

Index by position (int/slice), id list, boolean mask, or pl.Expr.

property agent_ids

property agents: List[Agent]

list of underlying Agent objects.

Type:

Legacy accessor

append(agent: Agent) → None

clear() → None

copy() → AgentList

count(agent: Agent) → int

extend(agents: List[Agent]) → None

get_data() → DataFrame

group_by(by: str) → Dict[Any, FilteredAgentList]

index(agent: Agent) → int

insert(idx: int, agent: Agent) → None

pop(idx: int = -1) → Agent

remove(agent: Agent) → None

reverse() → None

sort(key=None, reverse: bool = False) → None

The full population view. Lives at model.agents and acts as both the entry point for vectorized queries and a legacy list of Agent objects.

Vectorized usage (preferred):

# Filter by predicate and update columnar state
rich = model.agents.where(model.agents.wealth > 100)
rich.tag = 'rich'

# Scatter-add deltas for random id draws (duplicates sum correctly)
recipients = model.nprandom.choice(model.agents.ids.to_numpy(), size=50)
model.agents.at[recipients].scatter_add(wealth=1)

Legacy list usage (still supported):

# Indexing, iteration, append/remove — works as before
first = model.agents[0]
for agent in model.agents:
    agent.step()
model.agents.append(new_agent)

FilteredAgentList

class ambr.sequences.FilteredAgentList(model: Model, ids: Series, parent: AgentList)

Bases: _SubView

Subset view produced by agents.where(...) / agents[mask].

Returned from model.agents.where(...) or model.agents[mask]. Operates on the subset of rows matching a predicate. Writing to a column on this view touches only the filtered agents.

ScatterAgentList

class ambr.sequences.ScatterAgentList(model: Model, ids: Series, parent: AgentList)

Bases: _SubView

Id-indexed view produced by agents.at[ids] (ids may repeat).

Returned from model.agents.at[ids]. Unlike a filtered view, a scatter view can contain duplicate ids — which is the whole point for “random recipient” style updates. Use scatter_add to accumulate deltas when ids repeat; plain assignment falls back to last-write-wins semantics.

Features

• DataFrame-backed attribute reads and writes — no sync gotchas.

• Predicate filtering via where(...) with attribute predicates or raw Polars expressions.

• Scatter-add for flow-of-resources updates.

• Full back-compat with legacy list-style access (indexing, iteration, append/remove, call/apply).