Agent

class epiworldpy.Agent

Bases: pybind11_object

An individual in the simulated population.

Agents are created by the model (for example, with Model.agents_smallworld()) and accessed with Model.get_agent() or Model.get_agents(); they cannot be created directly. Each agent has a state (an index into Model.get_states()), at most one active virus, any number of tools, and may belong to entities.

Methods that change an agent (set_virus, add_tool, change_state, …) do not act immediately: they record an event that the model applies at the end of the current simulation step.

Methods

add_entity	Add the agent to an entity.
add_tool	Give the agent a tool.
change_state	Move the agent to a new state.
get_entities	Get the entities the agent belongs to.
get_id	Get the agent's ID.
get_n_entities	Get the number of entities the agent belongs to.
get_n_neighbors	Get the number of neighbors in the contact network.
get_n_tools	Get the number of tools the agent carries.
get_neighbors	Get the agent's neighbors in the contact network.
get_state	Get the agent's current state.
get_state_last_changed	Get the day the agent's state last changed.
get_state_prev	Get the agent's previous state.
get_tools	Get the tools the agent carries.
get_virus	Get the agent's active virus.
has_entity	Check whether the agent belongs to an entity, by ID.
has_neighbor	Check whether another agent is a neighbor.
has_tool	Overloaded function.
has_virus	Overloaded function.
mutate_virus	Mutate the agent's active virus.
rm_entity	Remove the agent from an entity.
rm_tool	Remove one of the agent's tools.
rm_virus	Remove the agent's active virus.
set_virus	Infect the agent with a virus.

add_entity(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, entity: epiworldpy._core.Entity) → None

Add the agent to an entity.

The agent joins the entity at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• entity (Entity) – The entity to join.

add_tool(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, tool: epiworldpy._core.Tool) → None

Give the agent a tool.

The agent receives a copy of tool at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• tool (Tool) – The tool to give to the agent.

change_state(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, new_state: SupportsInt | SupportsIndex, queue: SupportsInt | SupportsIndex = 0) → None

Move the agent to a new state.

The change takes effect at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• new_state (int) – Index of the new state (see Model.get_states()).

• queue (int, default 0) – How to update the queuing system (see Model.queuing_on()): 2 adds the agent and its neighbors to the queue, 1 adds only the agent, -1 and -2 undo those, and 0 leaves the queue unchanged.

get_entities(self: epiworldpy._core.Agent) → list[int]

Get the entities the agent belongs to.

Returns:

IDs of the entities (see Model.get_entity()).

Return type:

list of int

get_id(self: epiworldpy._core.Agent) → int

Get the agent’s ID.

Returns:

The agent’s ID, which is also its index in Model.get_agents().

Return type:

int

get_n_entities(self: epiworldpy._core.Agent) → int

Get the number of entities the agent belongs to.

Returns:

Number of entities.

Return type:

int

get_n_neighbors(self: epiworldpy._core.Agent) → int

Get the number of neighbors in the contact network.

Returns:

Number of neighbors.

Return type:

int

get_n_tools(self: epiworldpy._core.Agent) → int

Get the number of tools the agent carries.

Returns:

Number of tools.

Return type:

int

get_neighbors(self: epiworldpy._core.Agent, model: epiworldpy._core.Model) → list[epiworldpy._core.Agent]

Get the agent’s neighbors in the contact network.

Parameters:

model (Model) – The model the agent belongs to.

Returns:

The neighboring agents.

Return type:

list of Agent

get_state(self: epiworldpy._core.Agent) → int

Get the agent’s current state.

Returns:

Index of the state in Model.get_states().

Return type:

int

get_state_last_changed(self: epiworldpy._core.Agent) → int

Get the day the agent’s state last changed.

Returns:

Simulation day of the last state change.

Return type:

int

get_state_prev(self: epiworldpy._core.Agent) → int

Get the agent’s previous state.

Returns:

Index of the state the agent was in before its last state change.

Return type:

int

get_tools(self: epiworldpy._core.Agent) → list[epiworldpy._core.Tool]

Get the tools the agent carries.

Returns:

The agent’s tools, in the order they were received.

Return type:

list of Tool

get_virus(self: epiworldpy._core.Agent) → object

Get the agent’s active virus.

Returns:

The virus currently infecting the agent, or None if the agent is not infected.

Return type:

Virus or None

has_entity(self: epiworldpy._core.Agent, t: SupportsInt | SupportsIndex) → bool

Check whether the agent belongs to an entity, by ID.

Parameters:

t (int) – ID of the entity (see Entity.get_id()).

Returns:

True if the agent belongs to the entity.

Return type:

bool

has_neighbor(self: epiworldpy._core.Agent, neighbor_id: SupportsInt | SupportsIndex) → bool

Check whether another agent is a neighbor.

Parameters:

neighbor_id (int) – ID of the other agent.

Returns:

True if the other agent is one of this agent’s neighbors.

Return type:

bool

has_tool(*args, **kwargs)

Overloaded function.

1. has_tool(self: epiworldpy._core.Agent, t: typing.SupportsInt | typing.SupportsIndex) -> bool

Check whether the agent has a tool, by ID.

Parameters:

t (int) – ID of the tool (see Tool.get_id()).

Returns:

True if the agent carries the tool.

Return type:

bool

2. has_tool(self: epiworldpy._core.Agent, name: str) -> bool

Check whether the agent has a tool, by name.

Parameters:

name (str) – Name of the tool.

Returns:

True if the agent carries a tool with that name.

Return type:

bool

has_virus(*args, **kwargs)

Overloaded function.

1. has_virus(self: epiworldpy._core.Agent, t: typing.SupportsInt | typing.SupportsIndex) -> bool

Check whether the agent is infected with a virus, by ID.

Parameters:

t (int) – ID of the virus (see Virus.get_id()).

Returns:

True if the agent’s active virus has that ID.

Return type:

bool

2. has_virus(self: epiworldpy._core.Agent, name: str) -> bool

Check whether the agent is infected with a virus, by name.

Parameters:

name (str) – Name of the virus.

Returns:

True if the agent’s active virus has that name.

Return type:

bool

mutate_virus(self: epiworldpy._core.Agent, model: epiworldpy._core.Model) → None

Mutate the agent’s active virus.

Calls the virus’s mutation function (see Virus.set_mutation()).

Parameters:

model (Model) – The model the agent belongs to.

Raises:

RuntimeError – If the agent has no active virus.

rm_entity(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, entity: epiworldpy._core.Entity) → None

Remove the agent from an entity.

The agent leaves the entity at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• entity (Entity) – The entity to leave.

rm_tool(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, tool_idx: SupportsInt | SupportsIndex) → None

Remove one of the agent’s tools.

The tool is removed at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• tool_idx (int) – Position of the tool in get_tools() (not the tool’s ID).

rm_virus(self: epiworldpy._core.Agent, model: epiworldpy._core.Model) → None

Remove the agent’s active virus.

The agent moves to the virus’s end state (see Virus.set_state()) at the end of the current step.

Parameters:

model (Model) – The model the agent belongs to.

set_virus(self: epiworldpy._core.Agent, model: epiworldpy._core.Model, virus: epiworldpy._core.Virus) → None

Infect the agent with a virus.

The agent receives a copy of virus and moves to the virus’s init state (see Virus.set_state()) at the end of the current step.

Parameters:

• model (Model) – The model the agent belongs to.

• virus (Virus) – The virus to infect the agent with.