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 (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 (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:

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:

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:

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 (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:

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:

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, **kwargs)

Bases: 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 (Agent) –

  • ref_count (int) –

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 (Agent) –

  • ghost_ranks (Dict) –

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, **kwargs)

Bases: Protocol

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