repast4py.context module

class repast4py.context.SharedContext(comm)

Bases: object

Encapsulates a population of agents on a single process rank.

A SharedContext may have one or more projections associated with it to impose a relational structure on the agents in the context. It also provides functionality for synchronizing agents across processes, moving agents from one process to another and managing any ghosting strategy.

Parameters

comm (mpi4py.MPI.Intracomm) – the communicator used to communicate among SharedContexts in the distributed model

add(agent)

Adds the specified agent to this SharedContext.

The agent will also be added to any projections currently in this SharedContext

Parameters

agent (_core.Agent) – the agent to add

add_projection(projection)

Adds the specified projection to this SharedContext.

Any agents currently in this context will be added to the projection.

Parameters

projection (repast4py.core.SharedProjection) – the projection add

add_value_layer(value_layer)

Adds the specified value_layer to the this context.

Parameters

value_layer (repast4py.value_layer.SharedValueLayer) – the value layer to add.

agent(agent_id)

Gets the specified agent from the collection of local agents in this context.

Parameters

agent_id – the unique id tuple of the agent to return

Returns

The agent with the specified id or None if no such agent is found.

Return type

_core.Agent

Examples

>>> ctx = SharedContext(comm)
>>> # .. Agents Added
>>> agent1 = ctx.agent((1, 0, 1))
agents(agent_type=None, count=None, shuffle=False)

Gets the agents in this SharedContext, optionally of the specified type, count or shuffled.

Parameters

  • agent_type (int) – the type id of the agent, defaults to None.

  • count (int) – the number of agents to return, defaults to None, meaning return all the agents.

  • shuffle (bool) – whether or not the iteration order is shuffled. If true, the order is shuffled. If false, the iteration order is the order of insertion.

Returns

An iterable over all the agents in the context. If the agent_type is not None then an iterable over agents of that type will be returned.

Return type

iterable

Examples

>>> PERSON_AGENT_TYPE = 1
>>> for agent in ctx.agents(PERSON_AGENT_TYPE, shuffle=True):
       ...
get_projection(projection_name)

Gets the named projection.

Parameters

projection_name (str) – the name of the projection to get

Returns

The named projection.

Raises

KeyError – If the collection of projections in this SharedContext does not include the named projection.

Return type

repast4py.core.SharedProjection

ghost_agent(agent_id)

Gets the specified agent from the collection of ghost agents in this context.

Parameters

agent_id – the unique id tuple of the agent to return

Returns

The ghost agent with the specified id or None if no such agent is found.

Return type

_core.Agent

move_agents(agents_to_move, create_agent)

Moves agents from this rank to another rank where it becomes a local agent.

The list of agents to move must be agents currently local to this rank. This performs a synchronize after moving the agents in order synchronize the new location of the agents. This is a collective operation and all ranks must call it, regardless of whether agents are being moved to or from that rank.

Parameters

  • agents_to_move (List) – A list of tuples specifying agents to move and the rank to move the agent to. Each tuple must contain the agents unique id tuple and the rank, for example ((id, type, rank), rank_to_move_to).

  • create_agent (Callable) – a Callable that can take the result of an agent :samp: save() and return an agent.

remove(agent)

Removes the specified agent from this SharedContext

This agent is also removed from any projections associated with this SharedContext. If the agent is shared as a ghost on any other ranks it will be removed from those ranks during the next synchronization.

Parameters

agent (_core.Agent) – the agent to remove.

request_agents(requested_agents, create_agent)

Requests agents from other ranks to be copied to this rank as ghosts.

This is a collective operation and all ranks must call it, regardless of whether agents are being requested by that rank. The requested agents will be automatically added as ghosts to this rank.

Parameters

  • requested_agents (List) – A list of tuples specifying requested agents and the rank to request from. Each tuple must contain the agents unique id tuple and the rank, for example ((id, type, rank), requested_rank).

  • create_agent (Callable) – a Callable that can take the result of an agent save() and return an agent.

Returns

The list of requested agents.

Return type

List[_core.Agent]

size(agent_type_ids=None)

Gets the number of local agents in this SharedContext, optionally by type.

Parameters

agent_type_ids (List[int]) – a list of the agent type ids identifying the agent types to count. If this is None then the total size is returned with an agent type id of -1.

Returns

A dictionary containing the counts (the dict values) by agent type (the dict keys).

Return type

dict

synchronize(restore_agent, sync_ghosts=True)

Synchronizes the model state across processes by moving agents, filling projection buffers with ghosts, updating ghosted state and so forth.

Parameters

  • restore_agent (Callable) – a callable that takes agent state data and returns an agent instance from that data. The data is a tuple whose first element is the agent’s unique id tuple, and the second element is the agent’s state, as returned by that agent’s type’s save() method.

  • sync_ghosts (bool) – if True, the ghosts in any SharedProjections and value layers associated with this SharedContext are also synchronized. Defaults to True.