repast4py.network module

The network module contains classes and functions for simulating networks (i.e., graphs) where agents are the nodes in the network. The network code is built-on the networkx python package.

class repast4py.network.DirectedSharedNetwork(name, comm)

Bases: SharedNetwork

Encapsulates a directed network shared over multiple process ranks.

This wraps a networkx DiGraph object and delegates all the network related operations to it. That Graph is exposed as the graph attribute. See the networkx Graph documentation for more information on the network functionality that it provides. The network structure must NOT be changed using the networkx functions and methods (adding and removing nodes, for example). Use this class’ methods for manipulating the network structure.

graph

a networkx graph object wrapped by this class.

Type:

networkx.DiGraph

comm

the communicator over which the network is shared.

Type:

MPI.Comm

names

the name of this network.

Type:

str

Parameters:

  • name (str) – the name of the SharedNetwork

  • comm (Comm) – the communicator over which this DirectedSharedNetwork is distributed

add_edge(u_agent, v_agent, **kwattr)

Adds an edge beteen u_agent and v_agent.

If the u and v agents are not existing nodes in the network, they will be added. Edge attributes can be added using keyword arguments.

Parameters:

  • u_agent (Agent) – The u agent

  • v_agent (Agent) – The v agent

  • kwattr – optional keyword arguments for assigning edge data.

Examples

Add an edge with a weight attribute

>>> g.add_edge(agent1, agent2, weight=3.1)
property is_directed: bool

Gets whether or not this network is directed.

Returns:

True

num_edges(agent)

Gets the number of edges that contain the specified agent.

Returns:

The number of edges that contain the specified agent

Parameters:

agent (Agent) –

Return type:

int

class repast4py.network.SharedNetwork(name, comm, graph)

Bases: object

A network that can be shared across multiple process ranks through ghost nodes and edges. This is the base class for the Directed and Undirected SharedNetwork classes. This class should NOT be instantiated directly by users.

This wraps a networkx Graph object and delegates all the network related operations to it. That Graph is exposed as the graph attribute. See the networkx Graph documentation for more information on the network functionality that it provides. The network structure should _NOT_ be changed using the networkx functions and methods (adding and removing nodes, for example). Use this class’ methods for manipulating the network structure.

graph

a networkx graph object that provides the network functionality.

Type:

networkx Graph

Parameters:

  • name (str) – the name of the SharedNetwork

  • comm (Comm) – the communicator over which this SharedNetwork is distributed

  • graph (networkx Graph) –

    the networkx graph object that provides the network functionality.

add(agent)

Adds the specified agent as a node in the network.

Parameters:

agent (Agent) –

add_nodes(agents)

Adds each agent in the specified list of agents as nodes in the network.

Parameters:

agents (List[Agent]) – the list of agents to add

clear_edges()

Removes all the edges.

contains_edge(u_agent, v_agent)

Gets whether or not an edge exists between the u_agent and v_agent.

Parameters:

  • u_agent (Agent) – the u node of the edge.

  • v_agent (Agent) – the v node of the edge.

Returns:

True if an edge exists, otherwise False.

Return type:

bool

property edge_count: int

Gets the number of edges in this SharedNework.

property node_count: int

Gets the number of nodes in this SharedNetwork.

remove(agent)

Removes the specified agent from this SharedNetwork.

Parameters:

agent (Agent) – the agent to remove

Raises:

NetworkXError – if the agent is not a node in this SharedNetwork.

remove_edge(u_agent, v_agent)

Removes the edge between u_agent and v_agent.

Parameters:

  • u_agent (Agent) – the u node of the edge.

  • v_agent (Agent) – the v node of the edge.

Raises:

NetworkXError – if there is no edge between u_agent and v_agent.

update_edge(u_agent, v_agent, **kwattr)

Updates the edge between u_agent and v_agent with the specified attributes.

Parameters:

  • u_agent (Agent) – the u node of the edge

  • v_agent (Agent) – the v node of the edge

  • kwattr – keyword arguments containting the edge attribute updates

Examples

Update the weight attribute for the edge between agent1 and agent2.

>>> g.update_edge(agent1, agent2, weight=10.1)
class repast4py.network.UndirectedSharedNetwork(name, comm)

Bases: SharedNetwork

Encapsulates an undirected network shared over multiple processes.

This wraps a networkx Graph object and delegates all the network related operations to it. That Graph is exposed as the graph attribute. See the networkx Graph documentation for more information on the network functionality that it provides. The network structure should NOT be changed using the networkx functions and methods (adding and removing nodes, for example). Use this class’ methods for manipulating the network structure.

graph

a network graph object responsible for network operations.

Type:

networkx.Graph

comm

the communicator over which the network is shared.

Type:

MPI.Comm

name

the name of this network.

Type:

str

Parameters:

  • name (str) – the name of the SharedNetwork

  • comm (Comm) – the communicator over which this SharedNetwork is distributed

  • directed – specifies whether this SharedNetwork is directed or not

add_edge(u_agent, v_agent, **kwattr)

Adds an edge between u_agent and v_agent.

If the u and v agents are not existing nodes in the network, they will be added. Edge attributes can be added using keyword arguments.

Parameters:

  • u_agent (Agent) – The u agent

  • v_agent (Agent) – The v agent

  • kwattr – optional keyword arguments for assigning edge data.

Examples

Add an edge with a weight attribute

>>> g.add_edge(agent1, agent2, weight=3.1)
property is_directed: bool

Gets whether or not this network is directed. Returns False

Returns:

False

num_edges(agent)

Gets the number of edges that contain the specified agent.

Parameters:

agent (Agent) – agent whose edge will be counted

Returns:

The number of edges that contain the specified agent

Return type:

int

repast4py.network.read_network(fpath, ctx, create_agent, restore_agent)

Creates and initializes the network described in the specified file.

The network will be created and added to the specified context as a projection. The nodes defined in the file will be created as agents. Those agents with a local rank will be added to the specified context, and those remote agents that participate in an edge with a local agent with be added as ghost agents.

The format of the file is as follows. The first line consists of a network id (name) followed by a space followed by 0 or 1, where 0 indicates that the network is undirected and 1 that it is directed. This first line is followed the node descriptions. Each node description line defines a node and consists at least 3 space separated elements. These 3 are the node id, the agent type, and the rank on which the agent should be created. These 3 are optionally followed by a json dictionary string containing any attributes of that agent. The node descriptions should be followed by “EDGES” to indicate that the edge descriptions follow in the remaining lines. Each edge description line defines an edge and consists of at least 2 space separated elements. These two are the node ids of the u and v components of the edge. An optional 3rd element, a json dictionary, defines any attributes (e.g., weight) to associate with that edge. For example:

friend_network 0
1 0 1 {"age": 23}
2 0 1 {"age" : 24}
3 0 0 {"age" : 30}
EDGES
1 2 {"weight": 0.5}
3 1 {"weight": 0.75}

Without node or edge attributes::

friend_network 0
1 0 1
2 0 1
3 0 0
EDGES
1 2
3 1

The node id, the type and the rank elements are passed to a user specified Callable to create the agents. In that Callable, these 3 elements must be used to create the agents’ unique ids

Parameters:

  • fpath (str) – the path to the network description file.

  • ctx (repast4py.context.SharedContext) – the context to add the agents to

  • create_agent (Callable) – a Callable used to create an agent from a node description. The Callable must have the following signature (node_id: int, agent_type: int, rank: int, **agent_attributes) and return an agent.

  • restore_agent (Callable) – a Callable used to deserialize agents from agent data sent from another rank, that is, one that takes the tuple returned by an agent’s save() method and returns an agent.

repast4py.network.write_network(graph, network_name, fpath, n_ranks, **partition_args)

Partitions a specified network over the specified process ranks and writes that network to a file in a format that can be read by the repast4py.network.read_network() function. The intention is that write_network is used to create a distributed partitioned graph file outside of a running simulation, and once created that file can then be read during simulation initialization to create a repast4py network.

The format of the file is as follows. The first line consists of a network id (name) followed by a space followed by 0 or 1, where 0 indicates that the network is undirected and 1 that it is directed. This first line is followed the node descriptions. Each node description line defines a node and consists at least 3 space separated elements. These 3 are the node id, the agent type, and the rank on which the agent should be created. These 3 are optionally followed by a json dictionary string containing any attributes of that agent. The node descriptions should be followed by “EDGES” to indicate that the edge descriptions follow in the remaining lines. Each edge description line defines an edge and consists of at least 2 space separated elements. These two are the node ids of the u and v components of the edge. An optional 3rd element, a json dictionary, defines any attributes (e.g., weight) to associate with that edge. If a node in the graph contains an ‘agent_type’ attribute then that will written as the agent type id for that node, otherwise the type is 0.

The network is partitioned across process ranks by assigning each node to a rank. A partition_method can be specified in the partition_args and can be one of ‘random’ or ‘metis’. If no partition_method is defined, then the method defaults to random where the nodes will be uniformly distributed among the process ranks without any load balancing. A partition method of metis will use the metis load balancer to allocate nodes to ranks. Metis is not included with repast4py and must be installed separately. See the networkx metis docs for more information on installation and nxmetis. Note that installing from source or github may be necessary.

Parameters:

  • graph (Graph) – the graph to partition and write out.

  • network_name (str) – the id / name to assign to the partitioned network

  • fpath (str) – the path of the file to write the partitioned network to

  • n_ranks (int) – the number of ranks to partition the network over

  • partition_args –

    keyword arguments that determine how the graph will be partitioned.

    • The partition_method keyword is used to determine the partition method (‘random’ or ‘metis’).

    If partition_method is ‘random’:

    • rng specifies the random number generator to use in the random partitioning. Valid values are any numpy.random.Generator instance or ‘default’ to use the repast4py.random.default_rng. If no ‘rng’ is specified then by default the repast4py.random.default_rng is used.

    If partition_method is ‘metis’:

    • The partition_args are forwared to the nxmetis’ partition function. The various arguments to that can be found in the networkx metis reference.

Examples

Random Patitioning

>>> import networkx as nx
>>> g = nx.generators.dual_barabasi_albert_graph(60, 2, 1, 0.25)
>>> fname = './test_data/gen_net_test.txt'
>>> write_network(g, "test", fname, 3, partition_method='random', rng='default')

Metis Partitioning

>>> g = nx.complete_graph(60)
>>> options = nxmetis.types.MetisOptions(seed=1)
>>> write_network(g, "metis_test", fname, 3, partition_method='metis', options=options)