..  -*- coding: utf-8 -*-

A Quick Tour
============

Building and drawing a small graph
----------------------------------

We assume you can start an interactive Python session..
We will assume that you are familiar with Python terminology 
(see the official Python website http://www.python.org for more
information).
If you did not install NetworkX into the Python site directory 
it might be useful to add that directory to your PYTHONPATH.

After starting Python, import the networkx module with (the recommended way)

>>> import networkx as nx

To save repetition, in all the examples below we assume that 
NX has been imported this way.

You may also use the usual mode for interactive experimentation that might
clobber some names already in your name-space

>>> from networkx import *

If importing networkx fails, it means that Python cannot find the installed
module. Check your installation and your PYTHONPATH.

The following basic graph types are provided as Python classes:

Graph
   This class implements an undirected graph. It ignores
   multiple edges between two nodes.  It does allow self-loop
   edges between a node and itself.

DiGraph
   Directed graphs, that is, graphs with directed edges.
   Operations common to directed graphs, 
   (A subclass of Graph.)

MultiGraph
   A flexible graph class that allows multiple undirected edges between 
   pairs of nodes.  The additional flexibility leads to some degradation 
   in performance, though usually not significant.
   (A subclass of Graph.)

MultiDiGraph
   A directed version of a MultiGraph.  
   (A subclass of DiGraph.)

Empty graph-like objects are created with

>>> G=nx.Graph()
>>> G=nx.DiGraph()
>>> G=nx.MultiGraph()
>>> G=nx.MultiDiGraph()

When called with no arguments you get a graph without
any nodes or edges (empty graph).  In NX every graph or network is a Python
"object", and in Python the functions associated with an "object" are
known as methods.

All graph classes allow any hashable object as a node.   Hashable
objects include strings, tuples, integers, and more.
Arbitrary edge data/weights/labels can be associated with an edge.  

All graph classes have boolean attributes to describe the nature of the
graph:  directed, weighted, multigraph.
The weighted attribute means that the edge weights are numerical, though
that is not enforced.  Some functions will not work on graphs that do
not have weighted==True (the default), so it can be used to protect yourself
against using a routine that requires numerical edge data.

The graph classes data structures are based on an
adjacency list and implemented as a Python dictionary of
dictionaries. The outer dictionary is keyed by nodes to values that are
themselves dictionaries keyed by neighboring node to the
edge object (default 1) associated with that edge (or a list of edge
objects for MultiGraph/MultiDiGraph).  This "dict-of-dicts" structure
allows fast addition, deletion, and lookup of nodes and neighbors in 
large graphs.  The underlying datastructure is accessed directly 
by methods (the programming interface "API") in the class definitions.  
All functions, on the other hand, manipulate graph-like objects 
solely via those API methods and not by acting directly on the datastructure. 
This design allows for possible replacement of the 'dicts-of-dicts'-based 
datastructure with an alternative datastructure that implements the
same methods.

Glossary
--------

The following shorthand is used throughout NetworkX documentation and code:
 
G,G1,G2,H,etc
   Graphs

n,n1,n2,u,v,v1,v2:
   Nodes (vertices)

nlist,vlist:
   A list of nodes (vertices)

nbunch, vbunch:
   A "bunch" of nodes (vertices).
   An nbunch is any iterable container
   of nodes that is not itself a node in the graph. (It can be an
   iterable or an iterator, e.g. a list, set, graph, file, etc..)

e=(n1,n2), (n1,n2,x):
   An edge (a Python 2-tuple or 3-tuple),
   also written n1-n2 (if undirected) and n1->n2 (if directed).
 
e=(n1,n2,x): 
   The edge object x (or list of objects for multigraphs) associated 
   with an edge can be obtained using G.get_edge(n1,n2). 
   The default G.add_edge(n1,n2) is equivalent to G.add_edge(n1,n2,1). 
   In the case of multiple edges in multigraphs between nodes n1 and n2, 
   one can use G.remove_edge(n1,n2) to remove all edges between n1 and n2, or
   G.remove_edge(n1,n2,x) to remove one edge associated with object x. 

elist:
   A list of edges (as 2- or 3-tuples)

ebunch:
   A bunch of edges (as tuples).
   An ebunch is any iterable (non-string) container
   of edge-tuples. (Similar to nbunch, also see add_edge).

iterator method names:
   In many cases it is more efficient to iterate through items rather
   than creating a list of items.  
   NetworkX provides separate methods that return an iterator.  
   For example, G.degree() and G.edges() return lists while G.degree_iter() 
   and G.edges_iter() return iterators.


Some potential pitfalls to be aware of:

  - Although any hashable object can be used as a node, one should not
    change the object after it has been added as a
    node (since the hash can depend on the object contents).
  - The ordering of objects within an arbitrary nbunch/ebunch
    can be machine- or implementation-dependent.
  - Algorithms applicable to arbitrary nbunch/ebunch should treat 
    them as once-through-and-exhausted iterable containers.
  - len(nbunch) and len(ebunch) need not be defined.    



Graph methods
-------------

A Graph object G has the following primitive methods associated
with it. (You can use dir(G) to inspect the methods associated with object G.)

1. Non-mutating Graph methods::

    - len(G), G.number_of_nodes(), G.order()  # number of nodes in G
    - n in G,     G.has_node(n)       
    - for n in G:   # loop through the nodes in G
    - for nbr in G[n]:  # loop through the neighbors of n in G
    - G.nodes()        # list of nodes
    - G.nodes_iter()   # iterator over nodes
    - nbr in G[n],  G.has_edge(n1,n2), G.has_neighbor(n1,n2)
    - G.edges(), G.edges(n), G.edges(nbunch)      
    - G.edges_iter(), G.edges_iter(n), G.edges_iter(nbunch)
    - G.get_edge(n1,n2)  # the object associated with this edge
    - G.neighbors(n)     # list of neighbors of n
    - G.neighbors_iter(n) # iterator over neighbors
    - G[n]               # dictionary of neighbors of n keyed to edge object
    - G.adjacency_list  #list of 
    - G.number_of_edges(), G.size()
    - G.degree(), G.degree(n), G.degree(nbunch)
    - G.degree_iter(), G.degree_iter(n), G.degree_iter(nbunch)
    - G.nodes_with_selfloops()
    - G.selfloop_edges()
    - G.number_of_selfloops()
    - G.nbunch_iter(nbunch)  # iterator over nodes in both nbunch and G

    The following return a new graph::

    - G.subgraph(nbunch,copy=True)
    - G.copy() 
    - G.to_directed()
    - G.to_undirected()
    
2. Mutating Graph methods::

    - G.add_node(n), G.add_nodes_from(nbunch)
    - G.remove_node(n), G.remove_nodes_from(nbunch)
    - G.add_edge(n1,n2), G.add_edge(*e)
    - G.add_edges_from(ebunch)
    - G.remove_edge(n1,n2), G.remove_edge(*e), 
    - G.remove_edges_from(ebunch)
    - G.add_star(nlist)
    - G.add_path(nlist)
    - G.add_cycle(nlist)
    - G.clear()
    - G.subgraph(nbunch,copy=False)


Names of classes/objects use the CapWords convention,
e.g. Graph, MultiDiGraph. Names of functions and methods
use the lowercase_words_separated_by_underscores convention,
e.g. petersen_graph(), G.add_node(10).

G can be inspected interactively by typing "G" (without the quotes).
This will reply something like <networkx.base.Graph object at 0x40179a0c>.
(On Linux machines with CPython the hexadecimal address is the memory
location of the object.)