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 (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 (SharedProjection) – the projection add

add_value_layer(value_layer)

Adds the specified value_layer to the this context.

Parameters:

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:

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 (Optional[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):
       ...
contains_type(agent_type)

Get whether or not this SharedContexts contains any agents of the specified type

Parameters:

agent_type (int) – the agent type id

Returns:

True if this SharedContext does contains agents of the specified type, otherwise False.

Return type:

bool

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:

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:

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 (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[Agent]

size(agent_type_ids=None)

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

Parameters:

agent_type_ids (Optional[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.