Graph topologies (Network)

class Network(model, graph=None, **kwargs)

Agent environment with a graph topology. Every node of the network is a AgentNode that can hold multiple agents as well as node attributes.

This class can be used as a parent class for custom network types. All agentpy model objects call the method setup() after creation, and can access class attributes like dictionary items.

Parameters

• model (Model) – The model instance.

• graph (networkx.Graph, optional) – The environments’ graph. Can also be a DiGraph, MultiGraph, or MultiDiGraph. Nodes will be converted to AgentNode, with their original label being kept as AgentNode.label. If none is passed, an empty networkx.Graph is created.

• **kwargs – Will be forwarded to Network.setup().

Variables

• graph (networkx.Graph) – The network’s graph instance.

• agents (AgentIter) – Iterator over the network’s agents.

• nodes (AttrIter) – Iterator over the network’s nodes.

add_agents(agents, positions=None)

Adds agents to the network environment.

Parameters

• agents (Sequence of Agent) – Instance or iterable of agents to be added.

• positions (Sequence of AgentNode, optional) – The positions of the agents. Must have the same length as ‘agents’, with each entry being an AgentNode of the network. If none is passed, new nodes will be created for each agent.

add_node(label=None)

Adds a new node to the network.

Parameters

label (int or string, optional) – Unique name of the node, which must be different from all other nodes. If none is passed, an integer number will be chosen.

Returns

The newly created node.

Return type

AgentNode

move_to(agent, node)

Moves agent to new position.

Parameters

• agent (Agent) – Instance of the agent.

• node (AgentNode) – New position of the agent.

neighbors(agent)

Select agents from neighboring nodes. Does not include other agents from the agents’ own node.

Parameters

agent (Agent) – Instance of the agent.

Returns

Iterator over the selected neighbors.

Return type

AgentIter

record(var_keys, value=None)

Records an object’s variables at the current time-step. Recorded variables can be accessed via the object’s log attribute and will be saved to the model’s output at the end of a simulation.

Parameters

• var_keys (str or list of str) – Names of the variables to be recorded.

• value (optional) – Value to be recorded. The same value will be used for all var_keys. If none is given, the values of object attributes with the same name as each var_key will be used.

Notes

Recording mutable objects like lists can lead to wrong results if the object’s content will be changed during the simulation. Make a copy of the list or record each list entry seperately.

Examples

Record the existing attributes x and y of an object a:

a.record(['x', 'y'])

Record a variable z with the value 1 for an object a:

a.record('z', 1)

Record all variables of an object:

a.record(a.vars)

remove_agents(agents)

Removes agents from the network.

remove_node(node)

Removes a node from the network.

Parameters

node (AgentNode) – Node to be removed.

setup(**kwargs)

This empty method is called automatically at the objects’ creation. Can be overwritten in custom sub-classes to define initial attributes and actions.

Parameters

**kwargs – Keyword arguments that have been passed to Agent or Model.add_agents(). If the original setup method is used, they will be set as attributes of the object.

Examples

The following setup initializes an object with three variables:

def setup(self, y):
    self.x = 0  # Value defined locally
    self.y = y  # Value defined in kwargs
    self.z = self.p.z  # Value defined in parameters

class AgentNode(label)

Node of Network. Functions like a set of agents.

add()

Add an element to a set.

This has no effect if the element is already present.

clear()

Remove all elements from this set.

copy()

Return a shallow copy of a set.

difference()

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

difference_update()

Remove all elements of another set from this set.

discard()

Remove an element from a set if it is a member.

If the element is not a member, do nothing.

intersection()

Return the intersection of two sets as a new set.

(i.e. all elements that are in both sets.)

intersection_update()

Update a set with the intersection of itself and another.

isdisjoint()

Return True if two sets have a null intersection.

issubset()

Report whether another set contains this set.

issuperset()

Report whether this set contains another set.

pop()

Remove and return an arbitrary set element. Raises KeyError if the set is empty.

remove()

Remove an element from a set; it must be a member.

If the element is not a member, raise a KeyError.

symmetric_difference()

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

symmetric_difference_update()

Update a set with the symmetric difference of itself and another.

union()

Return the union of sets as a new set.

(i.e. all elements that are in either set.)

update()

Update a set with the union of itself and others.