repast4py.core module

This module implements core functionality used by both contexts and projections.

class repast4py.core.Agent(id, type, rank)

Bases: object

Parent class of all agents in a repast4py simulation.

Each agent must have an id that is unique among all agents over all the ranks of a simulation. This id is composed of an integer id, an agent type id, and the integer rank on which the agent is created. These components are the arguments to the Agent constructor

Parameters

  • id (int) – an integer that uniquely identifies this agent from among those of the same type and created on the same rank. Consequently, agents created on different ranks, or of different types but created on the same rank may have the same id.

  • type (int) – an integer that specifies the type of this agent.

  • rank (int) – the rank on which this agent is created.

id

Gets the id component from this agent’s unique id

Type

int

local_rank

Gets and sets the current local rank of this agent. Users should NOT need to access this value.

Type

int

type

Gets the type component from this agent’s unique id

Type

int

uid

Gets this agent’s unique id tuple (id, type, rank)

Type

Tuple(int, int, int)

uid_rank

Gets the rank component from this agent’s unique id

Type

int

class repast4py.core.AgentManager(rank, world_size)

Bases: object

Manages local and non-local (ghost) agents as they move between processes.

This is class is internal to the repast4py implementation and is NOT for users.

Parameters

  • rank (int) – the local process rank

  • world_size (int) – the total number of ranks in the model

add_ghost(ghosted_rank, agent, incr=1)

Adds the specified agent to the ghost collection from the specified rank.

Parameters

  • ghosted_rank (int) – the rank the agent was received from

  • agent (_core.Agent) – the agent to add

  • incr (int) – the amount to increment the reference count

add_ghosts_to_projection(projection)

Adds all the ghost agents to the specified projection.

Parameters

projection – The projection to add the ghosts to

add_local(agent)

Adds the specified agent as a local agent

Parameters

agent (_core.Agent) – the agent to add

add_req_ghost(agent_id)

Adds the specified agent to the set of requested agents that are ghosts on this rank.

Parameters

agent_id (Tuple) – the id of the ghost requested agent

delete_ghost(agent_id)

Deletes the specified ghost agent. This is used to clear the ghost when the non ghost has been removed from the simulation

Parameters

agent_id (Tuple) – the unique id tuple of the ghost.

delete_ghosted(agent_id)

Removes the specified agent from the collection of agents ghosted from this rank and returns the ranks it is ghosted to.

This is used when the ghosted agent moves off of a rank on to another rank.

Parameters

agent_id (Tuple) – the unique id tuple of the agent to remove from the ghosted collection

Returns

A dictionary where the key is the rank the agent is ghosted to, and the value is the projection reference count for the agent on that rank.

Return type

Dict[int, int]

delete_local(agent_id, ghosted_deleted)

Deletes the specified agent from the collection of local agents, and adds data any ghosts to be deleted.

Parameters

  • agent_id (Tuple) – the id of the agent to remove

  • ghosted_deleted (List) – appended with a GhostedAgent if the agent to be removed is ghosted on another rank.

Returns

The deleted agent or None if the agent does not exist

Return type

_core.Agent

get_ghost(agent_uid, incr=1)

Gets the agent with the specified id from the collection of ghost agents, or None if the agent does not exist in the ghost agent collection. If the agent exists, its projection reference count is incremented by the specified amount

Parameters

  • agent_uid (agent uid tuple) – the uid of the agent to get

  • incr (int) – the amount to increment the reference count

Returns

The specified agent or None if the agent is not in the ghost agent collection. If the agent exists, its projection reference count is incremented.

Return type

_core.Agent

get_local(agent_id)

Gets the specified agent from the collection of local agents.

Parameters

agent_id (Tuple) – the unique id of the agent to get.

Returns

The agent with the specified id or None if no such agent is in the local collection.

Return type

_core.Agent

is_ghosted_to(ghost_rank, agent_id)

Gets whether or not the specified agent is ghosted to the specified rank.

Parameters

  • ghost_rank (int) – the rank the agent is being sent to as a ghost

  • agent_id (Tuple) – the id of the agent to get

Returns

True if the agent is ghosted to the rank, otherwise False.

Return type

bool

is_requested(agent_id)

Gets whether or not the specified agent is requested as a ghost on this rank.

Parameters

agent_id (Tuple) – the id of the agent to check

Returns

True if the agent is requested as a ghost on this rank, otherwise False.

Return type

bool

remove_ghost(agent)

Decrements the ghost agents reference count and removes it from this rank, if its reference count is 0.

Parameters

agent (_core.Agent) – the agent to remove

remove_local(agent_id)

Removes the specified agent from the collection of local agents.

Parameters

agent_id (Tuple) – the id of the agent to remove

Returns

The removed agent or None if the agent does not exist

Return type

_core.Agent

set_as_ghosted(ghost_ranks, agent_id)

Sets the specified agent as ghosted from this rank to the specified ranks.

Parameters

  • ghost_ranks (Dict) – the ranks where the agent is a ghost on

  • agent_id (Tuple) – the id of the agent that is ghosted from this rank

tag_as_ghosted(ghost_rank, agent_id)

Gets the specified agent from the local collection and marks it as ghosted on the specified rank.

Parameters

  • ghost_rank (int) – the rank the agent is being sent to as a ghost

  • agent_id (Tuple) – the id of the agent to tag

Returns

The specified agent.

Return type

_core.Agent

untag_as_ghosted(ghost_rank, agent_id)

Decrements the ghosted reference count for the specified agent on the specifed rank.

If the reference count goes to 0, then the agent will no longer be ghosted to that rank.

Parameters

  • ghost_rank (int) – the rank the agent is being sent to as a ghost

  • agent_id (Tuple) – the id of the agent to tag

class repast4py.core.BoundedProjection(*args, **kwds)

Bases: typing.Protocol

Protocol class for projections that are bounded such that an agent can move beyond the bounds of one instance and into another on another rank.

class repast4py.core.GhostAgent(agent, ref_count)

Bases: object

A non-local agent copied from another rank.

GhostAgent is used by the AgentManager to track and manage ghosts agents on a rank.

This is class is internal to the repast4py implementation and is NOT for users.

Parameters

  • agent (_core.Agent) –

  • ref_count (int) –

Return type

None

agent

the ghost agent

Type

Agent

ref_count

a reference count tracking the number of projections on this rank that refer to the agent

Type

int

agent: Agent
ref_count: int
class repast4py.core.GhostedAgent(agent, ghost_ranks)

Bases: object

An agent local to this rank that has been copied or “ghosted” to another rank.

GhostedAgent is used by the AgentManager to track and manage agents that have been ghosted from this rank to other ranks.

This is class is internal to the repast4py implementation and is NOT for users.

Parameters

  • agent (_core.Agent) –

  • ghost_ranks (Dict) –

Return type

None

agent

the ghosted agent

Type

Agent

ghost_ranks

maps the ghosted to rank to the number references the agent has on that rank.

Type

Dict

agent: Agent
ghost_ranks: Dict
class repast4py.core.SharedProjection(*args, **kwds)

Bases: typing.Protocol

Protocol class that defines the API for projections that are shared across multiple processes