Class Network

java.lang.Object
sim.field.network.Network
All Implemented Interfaces:
Serializable

public class Network extends Object implements Serializable
The Network is a field which stores binary graph and multigraph structures of all kinds, using hash tables to allow reasonably rapid dynamic modification.

The nodes of a Network's graph can be any arbitrary, properly hashable object. The edges of the graph are members of the Edge class. This class is little more than a wrapper around an arbitrary object as well (the Edge's 'info' object). Thus your graph's nodes and edges can essentially be objects entirely of your choosing.

Edge objects also contain pointers to the Nodes that they are to and from (plus some auxillary index information for speed).

Nodes and Edges are stored in the Network using two data structures: a Bag containing all the nodes in the Field; and a Map which maps each Node to a container holding the Node's index (position) in the Bag, plus a Bag of the Node's outgoing Edges and a Bag of the Node's incoming Edges. Ordinarily you won't fool with these structures other than to scan through them (in particular, to scan rapidly through the allNodes bag rather than use an iterator).

To add a node to the Network, simply use addNode(node). To remove a node, use removeNode(node). To add an edge to the Network, use addEdge(fromNode,toNode,edgeInfoObject), where edgeInfoObject is your arbitrary edge object. Alternatively, you can make an Edge object from scratch and add it with addEdge(new Edge(fromNode, toNode, edgeInfoObject)). You remove edges with removeEdge(edge). If you add an edge, and its nodes have not been added yet, they will automatically be added as well.

Traversing a Network is easy. To get a Bag of all the incoming (or outgoing) Edges to a node, use getEdgesIn(node) or getEdgesOut(node). Do not add or remove Edges from this Bag -- it's used internally and we trust you here. Also don't expect the Bag to not change its values mysteriously later on. Make a copy of the Bag if you want to keep it and/or modify it. Once you have an Edge, you can call its to() method and from() methods to get the nodes it's from and to, and you can at any time get and modify its info object. The to() and from() are fast and inlined.

However, the getEdgesIn(node) and getEdgesOut(node) methods are not super fast: they require a hash lookup. If you are planning on applying an algorithm on the Network which doesn't change the topology at all but traverses it a lot and changes just the contents of the edge info objects and the node object contents, you might consider first getting an adjacency list for the Network with getAdjacencyList(...), or an adjacency matrix with getAdjacencyMatrix(...) or getMultigraphAdjacencyMatrix(...). But remember that as soon as the topology changes (adding/deleting a node or edge), the adjacency list is invalid, and you need to request another one.

Computational Complexity. Adding a node or an edge is O(1). Removing an edge is O(1). Removing a node is O(m), where m is the total number of edges in and out of the node. Removing all nodes is O(1) and fast. Getting the in-edges or out-edges for a node is O(1). Getting the to or from node for an edge is O(1) and fast.

Warning About Hashing. Java's hashing method is broken in an important way. One can override the hashCode() and equals() methods of an object so that they hash by the value of an object rather than just the pointer to it. But if this is done, then if you use this object as a key in a hash table, then change those values in the object, it will break the hash table -- the key and the object hashed by it will both be lost in the hashtable, unable to be accessed or removed from it. The moral of the story is: do not override hashCode() and equals() to hash by value unless your object is immutable -- its values cannot be changed. This is the case, for example, with Strings, which hash by value but cannot be modified. It's also the case with Int2D, Int3D, Double2D, and Double3D, as well as Double, Integer, etc. Some of Sun's own objects are broken in this respect: Point, Point2D, etc. are both mutable and hashed by value.

This affects you in only one way in a Network: edges are hashed by nodes. The Network permits you to use any object as a node -- but you have been suitably warned: if you use a mutable but hashed-by-value node object, do NOT modify its values while it's being used as a key in the Network, at least not values which are used to compute its hash function.

Directed vs. Undirected Graphs. Networks are constructed to be either directed or undirected, and they cannot be changed afterwards without being entirely cleared first (using reset(...)). If the network is directed, then an Edge's to() and from() nodes have explicit meaning: the Edge goes from() one node to() another. If the network is undirected, then to() and from() are simply the two nodes at each end of the Edge with no special meaning, though they're always consistent. The convenience method edge.getOtherNode(node) will provide "other" node (if node is to(), then from() is returned, and vice versa). This is particularly useful in undirected graphs where you could be entering an edge as to() or as from() and you just want to know what the node on the other end of the edge is.

There are three methods for getting all the edges attached to a node: getEdgesIn(), getEdgesOut(), and the less efficient getEdges(). These methods work differently depending on whether or not the network is directed:

DirectedUndirected
getEdgesIn()Bag of incoming edgesBag of all edges
getEdgesOut()Bag of outgoing edgesBag of all edges
getEdges()Modifiable Bag of all edgesModifiable Bag of all edges

Hypergraphs. Network is binary. In the future we may provide a Hypergraph facility if it's needed, but for now you'll need to make "multi-edge nodes" and store them in the field, then hook them to your nodes via Edges. For example, to store the relationship foo(node1, node2, node3), here's one way to do it:

  1. Make a special foo object.
  2. field.addEdge(foo,node1,new Double(0));
  3. field.addEdge(foo,node2,new Double(1));
  4. field.addEdge(foo,node3,new Double(2));
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    The structure stored in the indexOutInHash hash table.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    All the objects in the sparse field.
    static final int
    Pass this into buildMap to indicate that it should make a map of any size it likes.
    Hashes Network.IndexOutIn structures by Node.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a directed graph
    Network(boolean directed)
    Constructs a directed or undirected graph.
    Constructs copy of an existing graph.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addEdge(Object from, Object to, Object info)
    Add an edge, storing info as the edge's associated information object.
    void
    addEdge(Edge edge)
    Add an edge.
    void
    Add a node
    buildMap(int size)
    Creates a map of the provided size (or any size it likes if ANY_SIZE is passed in).
    buildMap(Map other)
    Creates a Map which is a copy of another.
    Removes all nodes, deleting all edges from the Field as well.
    Deprecated. 
    Edge[][]
    getAdjacencyList(boolean outEdges)
    Creates and returns an adjacency list.
    Edge[][]
    Creates and returns a simple adjacency matrix, where only one edge between any two nodes is considered -- if you're using a multigraph, use getMultigraphAdjacencyMatrix() instead.
    Returns all the objects in the Sparse Field.
    getEdge(Object from, Object to)
    Returns an arbitrary edge connecting the "from" node to the "to" node, if one exists, else returns null.
    getEdges(Object from, Object to, Bag bag)
    Clears the provided Bag, then places in it all edges connecting the "from" node to the "to" node.
    getEdges(Object node, Bag bag)
    Get all the edges that enter or leave a node.
    Get all edges that enter a node.
    Get all edges that leave a node.
    getGraphComplement(boolean allowSelfLoops)
    Complements the graph: same nodes, no edges where they were, edges where they were not.
    Edge[][][]
    Creates and returns a multigraph adjacency matrix, which includes all edges from a given node to another -- if you know for sure that you have a simple graph (no multiple edges between two nodes), use getAdjacencyMatrix instead.
    int
     
    boolean
     
    Iterates over all objects.
    boolean
     
    void
    Remove all the edges in the network.
    Synonym for clear(), here only for backward-compatibility.
    Removes an edge and returns it.
    Removes a node, deleting all incoming and outgoing edges from the Field as well.
    void
    reset(boolean directed)
    Resets the network, clearing it of nodes and edges.
    void
    This reverse the direction of all edges in the graph.
    updateEdge(Edge edge, Object from, Object to, Object info)
    Removes the given edge, then changes its from, to, and info values to the provided ones, then adds the edge to the network again.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • indexOutInHash

      public Map indexOutInHash
      Hashes Network.IndexOutIn structures by Node. These structures contain the incoming edges of the Node, its outgoing edges, and the index of the Node in the allNodes bag.
    • allNodes

      public Bag allNodes
      All the objects in the sparse field. For fast scans. Do not rely on this bag always being the same object.
    • ANY_SIZE

      public static final int ANY_SIZE
      Pass this into buildMap to indicate that it should make a map of any size it likes.
      See Also:
  • Constructor Details

    • Network

      public Network(boolean directed)
      Constructs a directed or undirected graph.
    • Network

      public Network()
      Constructs a directed graph
    • Network

      public Network(Network other)
      Constructs copy of an existing graph.
  • Method Details

    • isDirected

      public boolean isDirected()
    • reset

      public void reset(boolean directed)
      Resets the network, clearing it of nodes and edges.
    • getAdjacencyList

      public Edge[][] getAdjacencyList(boolean outEdges)
      Creates and returns an adjacency list. If you're doing lots of operations (especially network traversals) which won't effect the topology of the network, an adjacency list structure might be more efficient for you to access rather than lots of calls to getEdgesIn() and getEdgesOut() etc. Building the list is an O(#edges) operation.

      The adjacency list is an array of Edge arrays. Each edge array holds all outgoing edges from a node (if outEdges is true -- otherwise it's the incoming edges to the node). The edge arrays are ordered in their parent array in the same order that the corresponding nodes are ordered in the allNodes bag.

      As soon as you modify any part of the Network's topology (through addEdge(), addNode(), removeEdge(), removeNode(), removeAllNodes(), etc.), the adjacency list data is invalid and should not be used. Instead, request a new adjacency list.

      You can modify these edge arrays any way you like, though the Edge objects are the actual Edges used in the Network. This means you can't add them to another Nework, though you can add copies of them (as in myNewNetwork.add(new Edge(myAdjacencyList[i][j])); )

    • getAdjacencyMatrix

      public Edge[][] getAdjacencyMatrix()
      Creates and returns a simple adjacency matrix, where only one edge between any two nodes is considered -- if you're using a multigraph, use getMultigraphAdjacencyMatrix() instead. If you're doing lots of operations (especially network traversals) which won't effect the topology of the network, an adjacency matrix structure might be more efficient for you to access rather than lots of calls to getEdgesIn() and getEdgesOut() etc. Building the matrix is an O(#edges + #nodes^2) operation.

      The adjacency matrix is a two-dimensional array of Edges, each dimension as long as the number of nodes in the graph. Each entry in the array is either an Edge FROM a node TO another, or it is null (if there is no such edge). If there are multiple edges between any two nodes, an arbitrary one is chosen. The Edge array returned is organized as Edge[FROM][TO]. The indices are ordered in the same order that the corresponding nodes are ordered in the allNodes bag.

      As soon as you modify any part of the Network's topology (through addEdge(), addNode(), removeEdge(), removeNode(), removeAllNodes(), etc.), the adjacency matrix data is invalid and should not be used. Instead, request a new adjacency matrix.

      You can modify these edge arrays any way you like, though the Edge objects are the actual Edges used in the Network. This means you can't add them to another Nework, though you can add copies of them (as in myNewNetwork.add(new Edge(myAdjacencyList[i][j])); )

    • getMultigraphAdjacencyMatrix

      public Edge[][][] getMultigraphAdjacencyMatrix()
      Creates and returns a multigraph adjacency matrix, which includes all edges from a given node to another -- if you know for sure that you have a simple graph (no multiple edges between two nodes), use getAdjacencyMatrix instead. If you're doing lots of operations (especially network traversals) which won't effect the topology of the network, an adjacency matrix structure might be more efficient for you to access rather than lots of calls to getEdgesIn() and getEdgesOut() etc. Building the matrix is expensive: it's an O(#edges + #nodes^2) operation.

      The adjacency matrix is a two-dimensional array of Edge arrays, both of the dimensions as long as the number of nodes in the graph. Each entry in this two-dimensional array is an array of all edges FROM a node TO another. Thus the returned array structure is organized as Edge[FROM][TO][EDGES]. The FROM and TO indices are ordered in the same order that the corresponding nodes are ordered in the allNodes bag.

      Important note: if there are no edges FROM a given node TO another, an empty array is placed in that entry. For efficiency's sake, the same empty array is used. Thus you should not assume that you can compare edge arrays for equality (an unlikely event anyway).

      As soon as you modify any part of the Network's topology (through addEdge(), addNode(), removeEdge(), removeNode(), removeAllNodes(), etc.), the adjacency matrix data is invalid and should not be used. Instead, request a new adjacency matrix.

      You can modify these edge arrays any way you like, though the Edge objects are the actual Edges used in the Network. This means you can't add them to another Nework, though you can add copies of them (as in myNewNetwork.add(new Edge(myAdjacencyList[i][j])); )

    • getEdgesOut

      public Bag getEdgesOut(Object node)
      Get all edges that leave a node. Do NOT modify this Bag -- it is used internally.
    • getEdgesIn

      public Bag getEdgesIn(Object node)
      Get all edges that enter a node. Do NOT modify this Bag -- it is used internally.
    • getEdges

      public Bag getEdges(Object node, Bag bag)
      Get all the edges that enter or leave a node. If a Bag is provided, it will be cleared, then filled and returned. Else a Bag will be constructed and returned. If the graph is undirected, then edgesIn and edgesOut should be the same thing, and so this is roughly equivalent to bag.addAll(getEdgesIn(node)); If the graph is directed, then both the edgesIn AND the edgesOut are added to the Bag. Generally speaking you should try to use the more efficient getEdgesIn(...) and getEdgesOut(...) methods instead if you can.
    • getEdge

      public Edge getEdge(Object from, Object to)
      Returns an arbitrary edge connecting the "from" node to the "to" node, if one exists, else returns null. If the graph is undirected, which node is "from" vs. "to" does not matter.
    • getEdges

      public Bag getEdges(Object from, Object to, Bag bag)
      Clears the provided Bag, then places in it all edges connecting the "from" node to the "to" node. Returns the Bag. If null is passed in for the Bag, then a new one is created and returned. If the graph is undirected, which node is "from" vs. "to" does not matter.
    • addNode

      public void addNode(Object node)
      Add a node
    • addEdge

      public void addEdge(Object from, Object to, Object info)
      Add an edge, storing info as the edge's associated information object. If you add an edge, and its nodes have not been added yet, they will automatically be added as well.
    • addEdge

      public void addEdge(Edge edge)
      Add an edge. If you add an edge, and its nodes have not been added yet, they will automatically be added as well. Throws an exception if the edge is null or if it's already added to a Field (including this one).
    • updateEdge

      public Edge updateEdge(Edge edge, Object from, Object to, Object info)
      Removes the given edge, then changes its from, to, and info values to the provided ones, then adds the edge to the network again. Ordinarily you wouldn't need to do this -- you can just remove an edge and add a new one. But in the case that you want to reuse an edge (to track it in an inspector, for example), this function might be helpful given that Edge specifically denies you the ability to change its to and from values.
    • removeEdge

      public Edge removeEdge(Edge edge)
      Removes an edge and returns it. The edge will still retain its info, to, and from fields, so you can add it again with addEdge. Returns null if the edge is null or if there is no such edge added to the field.
    • removeAllEdges

      public void removeAllEdges()
      Remove all the edges in the network.
    • removeNode

      public Object removeNode(Object node)
      Removes a node, deleting all incoming and outgoing edges from the Field as well. Returns the node, or null if there is no such node in the field.
    • clear

      public Bag clear()
      Removes all nodes, deleting all edges from the Field as well. Returns the nodes as a Bag, which you are free to modify as it's no longer used internally by the Network.
    • removeAllNodes

      public Bag removeAllNodes()
      Synonym for clear(), here only for backward-compatibility. Removes all nodes, deleting all edges from the Field as well. Returns the nodes as a Bag, which you are free to modify as it's no longer used internally by the Network.
    • getAllNodes

      public Bag getAllNodes()
      Returns all the objects in the Sparse Field. Do NOT modify the bag that you receive out this method -- it is used internally. If you wish in modify the Bag you receive, make a copy of the Bag first, using something like new Bag(foo.getallNodes()).
    • iterator

      public Iterator iterator()
      Iterates over all objects. NOT fail-fast, and remove() not supported. Use this method only if you're woozy about accessing allObject.numObjs and allObject.objs directly. For the fastest scan, you can do:

      for(int x=0;x<field.allNodes.numObjs;x++) ... field.allNodes.objs[x] ...

      ... but do NOT modify the allNodes.objs array.

    • nodeExists

      public boolean nodeExists(Object node)
    • getNodeIndex

      public int getNodeIndex(Object node)
    • reverseAllEdges

      public void reverseAllEdges()
      This reverse the direction of all edges in the graph. It is more expensive to clone the graph than to reverse the edges in place. It is more than twice as fast to reverse the edges than to create the dual graph. As a matter of fact getDualNetwork() took 240 time units while two reverseAllEdges() calls took only 40 time units on a directed graph (1time unit = 1 millisecond / 10000 calls). In that case it is more advantageous to reverse the edges, compute whatever stats on the dual and revert it than to allocate memory.
    • cloneGraph

      public Network cloneGraph()
      Deprecated.
      Makes a duplicate copy of the graph.
    • getGraphComplement

      public Network getGraphComplement(boolean allowSelfLoops)
      Complements the graph: same nodes, no edges where they were, edges where they were not. An advantage over calling addNode and addEdge n and m times, is to allocate the Bags the right size the first time.
    • buildMap

      public Map buildMap(Map other)
      Creates a Map which is a copy of another. By default, HashMap is used.
    • buildMap

      public Map buildMap(int size)
      Creates a map of the provided size (or any size it likes if ANY_SIZE is passed in). By default, HashMap is used.