Tulip Library

Introduction
Efficient visualization of graphs and their usage for data analysis implies
the manipulation of the structure of the graph
the extraction of parts of it
association of values to a graph's elements (nodes and edges)
the computation of intrinsic parameters (parameters derived from a graph's structure, e.g. in a filesystem graph (directory tree): number of files in a directory, can be computed by counting outgoing edges)
the computation of extrinsic parameters (parameters derived from external information, e.g. in a filesystem graph: file size)
This chapter describes the Tulip data structure that takes into account all the requirement of a graph visualization system. For each part we describe the general principle and then we give examples explaining how to do it with the Tulip library.

Graphs
The core of the Tulip library provides an interface for the manipulation of graphs. It enables one to access and modify the structure of a graph. The aim of this library is to be as general as possible and thus it manipulates a general class of graphs called directed pseudo-graphs. In a pseudo graph, there can be more than one edge between two nodes, and loops are permitted. A loop is an edge that links a node to itself. Furthermore, edges are directed, thus an edge u->v is distinct from an edge v->u.
Because we use pseudo-graphs, there can be more than one edge u->v, so it is not possible to distinguish two edges using only source and target (u,v). To make this possible, all the elements in Tulip are entities (C++ objects). Thus, even if two edges have the same source and the same target, they are distinct.
The elements of a graph are encapsulated in the graph. It is therefore not possible to access the graph's structure through elements, all operations must be done by querying the graph. For example, to know the source of an edge e of graph G, one must ask G, not e, what e's source is. This makes the use of the library less intuitive, but it minimizes memory usage for entities and allows to share them between subgraphs. Building a container of elements is cheap, because to handle elements, Tulip uses objects which use the same amount of storage as integers.
The library supports access and modification of the graph structure. The access to the structure are made by using iterators, one very important point is that the iterator are not persistent. Thus, if one modify the graph structure all the iterators on the graph structure can be invalid. This property enables to prevent from cloning the data structure and thus enables better access to it. For ease of use, Tulip includes mechanism that enables to transform an iterator into stable iterator, one must keep in mind that it corresponds to clone the data structure and thus, it should be use only if it is necessary.
If one uses Tulip only for the manipulation of one graph (no graph hierarchy), the list of available operations on the graph is given afterward. In the next section we will enhance the set of operations and the actions that they perform in order to manage a hierarchy of subgraphs

List of available modification operations
node addNode() : creates a new node in the graph and returns its identifier.
edge addEdge(node,node) : create a new edge in the graph, given the source and target.
void delNode(node) : deletes the given node.
void delEdge(edge) : deletes the given edge.
void reverse(edge) : reverses an edge (swaps source and target).

List of available access operations
unsigned int deg(node) : returns the degree of a node (number of edges).
unsigned int indeg(node) : returns the in degree of a node (number of times it is a target).
unsigned int outdeg(node) : returns the out degree of a node (number of times it is a source).
node source(edge) : returns the source of an edge.
node target(edge) : returns the target of an edge.
node opposite(edge,node) : it enables to obtain the opposite of a node of an edge.
Iterator * getInNodes(node) : returns an iterator on the predecessor nodes of a node.
Iterator * getOutNodes(node) : returns an iterator on the successor nodes of a node.
Iterator * getInOutNodes(node) : returns an iterator on the neighbor nodes of a node.
Iterator * getInEdges(node) : returns an iterator on the predecessor edges of a node.
Iterator * getOutEdges(node) : returns an iterator on the successor edges of a node.
Iterator * getInOutEdges(node) : returns an iterator on the neighbor edges of a node.

Hierarchy of graphs
The Tulip library can also manage subgraphs. By definition a subgraph G' of a graph G is part (subset) of the elements of G such that G' is also a graph (all sources and targets of the edges of G' must be in G'). As a subgraph is also a graph it can itself contain subgraphs. In such a hierarchy, if a graph G" is a descendant of a graph G, G" is also a subgraph of G.
One of the strong point of Tulip is to ensure efficiently that all elements are shared between graphs in a hierarchy of graphs. Thus, if a node n is an element of a graph G and of a graph G', the entity n is the same in both graphs. Of course, the parameters of the entity can change between graphs. For instance, the degree of n can be smaller for a subgraph, as it can have less edges.
The subgraph relation in the hierarchy is preserved when one modifies a graph. This means that if one adds a node to a graph, this node is automatically added to all its ancestors as well. If one deletes a node, this node is automatically deleted from all the descendants of the graph. If one reverses an edge, this edge is reversed in all the graphs of the hierarchy.
In order to manipulate a hierarchy of graphs, more functions have been added to those introduced above. They provide navigation and modification for the hierarchy. The access to the hierarchy is provided by iterators, which are not persistent and thus, if the hierarchy is modified, the iterators are invalid.

List of available modification operations
Graph *addSubGraph() : returns an empty subgraph of this graph.
Graph *delSubGraph(Graph *) : deletes a subgraph. Its descendants continue to be descendants of this graph.
Graph *delAllSubGraph(Graph *) : deletes a subgraph and all its descendants.
edge addEdge(edge) : adds an edge element from another graph in the hierarchy.
void addNode(node) : adds a node element from another graph in the hierarchy.

List of available access operations
Iterator * getSubGraphs() : returns an iterator on the subgraphs.
Graph * getSuperGraph() : returns the parent of the graph. If the graph has no parent, it returns the graph itself.

Attributes
An attributes is a kind of property that can be associated to a graph. An attributes has a name (a string) and a value of any type. It can be, for example ,the name of a graph, or a date of creation of the graph.
Attributes can be added and accessed with those three following member functions :
const DataSet getAttributes() : returns the attributes of a graph.
template<typename ATTRIBUTETYPE>bool getAttribute(const std::string &name, ATTRIBUTETYPE &value) : get an attribute.
template<typename ATTRIBUTETYPE>void setAttribute (const std::string &name, const ATTRIBUTETYPE &value) : set a new attribute value.

Properties
In Tulip, a property is an attribute of an element of a graph. It is called a property in order to prevent confusion with attributes of a graph: properties are for elements and attributes are for graphs. In Tulip, a property is always defined for both kinds of elements (nodes and edges), so one can always query for the value of the property associated with any edge or node.
To access the value of an elements one must query the graph for a property. This makes the use of the library less intuitive, but it minimizes memory usage for properties.
A property can be seen as an associative table where you can set and get the value for every element. All property operations have a TYPE argument, so there is no need to cast the result of a property query. The standard operations of a property are:

List of available modification operations
void setNodeValue(node,TYPE) : sets the value of a node.
void setAllNodeValue(TYPE) : sets the value of all nodes.
void setEdgeValue(edge,TYPE) : sets the value of an edge.
void setAllEdgeValue(TYPE) : sets the value of all edges.

List of available access operations
TYPE getNodeValue(node) : returns the value of a node.
TYPE getEdgeValue(edge) : returns the value of an edge.
For each property type there is a specific implementation (subclass) that allows operations which are specific to the property type (see Tulip libraries documentation). For instance, it is possible to obtain the maximum value of a property if the property type is double.
A graph includes a set of functions that enables to obtain/create/delete a property. Because the C++ signature of functions does not include the return type, the syntax for this call is not very simple. For instance, if one wants to obtain a property containing double (called DoubleProperty in Tulip) one must use the following syntax : DoubleProperty *metric=graph->getProperty<DoubleProperty>("name of the property"); In the graph each property is identified by its name which is a std::string, when one asks for a property the type of this property is checked using the run time type interrogation mechanism of C++. Warning: This test only happens when one compiles its sources in DEBUG mode (default mode). In order to facilitate the navigation/edition of the set of properties, a set of functions is accessible through the graph interface.

List of available operations
Iterator * getLocalProperties() : returns an iterator on all properties of this graph.
void delLocalProperty(const std::string&) : deletes a property.
bool existLocalProperty(const std::string&) : returns true if the property exists.
PropertyType * getLocalProperty (const std::string&) : returns the property. If it did not exist, creates it first
For the property mechanism described above to work with a hierarchy of graphs, a mechanism have been added to share properties between graphs, which works like this: if a property exists in an ancestor of a graph G, it also exists in the graph G. Thus, properties of graphs are inherited like members of objects in object-oriented languages. In order to facilitate the navigation/edition of properties, a set of function is accessible through the graph interface.

List of available operations
Iterators * getInheritedProperties() : returns an iterator on all properties (both inherited and local).
bool existProperty(const std::string&) : returns true if the property exists (inherited or local).
PropertyType * getProperty(const std::string&) : returns the property (inherited or local). If it did not exist, creates it first (locally)

TUTORIAL Intro.
Before doing any of the tutorials please read the following warnings :
Follow the tutorials, one by one, from the first one to the last one.
You can find at the end of each tutorial, the integral source code that we used.
If you want more details on a specific function or class please read the Tulip Graph library documentation.

TUTORIAL 001 : Graphs creation, adding and deleting nodes or edges.
In this first tutorial, we will show you how to create a graph, add three nodes and three edges, remove an edge and a node, and finally, print the result on the standard output.

1. Header files
Let's start with the files we need to include :

#include <iostream>
#include <tulip/Graph.h>

iostream : This "file" contains the C++ standard declarations for in and out streams. We need it in this tutorial to print the final graph on the standard output.
tulip/Graph.h : This file is the core of the tulip graph API. It provides declarations for graphs (edges , nodes) and functions to load one from a file, to save one, and a lot more. You can find a list in the Tulip Graph library documentation.
The namespaces usage declarations, so that we can omit namespace prefix.

using namespace std;
using namespace tlp;

2. Creation of a Graph
Create an empty graph with the function Graph* tlp::newGraph( ). This function returns a pointer on a empty Graph.

int main() {
  //create an empty graph
  Graph *graph = tlp::newGraph();

3. Add nodes
In the following, we are adding three nodes with the member function node Graph::addNode () that will, create an instance of a 'node', add it to the graph, and return it.
Using this function, the node is also added in all the graph ancestors to maintain the sub-graph relation between graphs.

  //add three nodes
  node n1 = graph->addNode();
  node n2 = graph->addNode();
  node n3 = graph->addNode();

4. Add edges
Now that nodes are created, we can create the edges. To do so, we can use the function edge Graph::addEdge ( const node, const node ) that will, add a new edge in the graph and return it.
The edge is also added in all the super-graph of the graph to maintain the sub-graph relation between graphs.
The first parameter is the "source node", and, of course, the second is the "target node" (in tulip, every edge are oriented but you can choose not to consider the orientation). We will see later (TUTORIAL 005) that the edges enumeration order is the one in which they are added.

  //add three edges
  edge e1 = graph->addEdge(n2,n3);
  edge e2 = graph->addEdge(n1,n2);
  edge e3 = graph->addEdge(n3,n1);

Following is a picture of the graph that we just have created. It is being displayed with tulip.

5. Delete an edge and a node
The Graph class provides member functions to delete edges and nodes.
void tlp::Graph::delEdge (const edge) : delete an edge of the graph. This edge is also removed in all the sub-graphs hierarchy to maintain the sub-graph relation between graphs. The ordering of edges is preserved.
void tlp::Graph::delNode ( const node ) : delete a node of the graph. This node is also removed in all the sub-graph of the graph to maintain the sub-graph relation between graphs. When the node is deleted, all its edges are deleted (in and out edges).
The class Graph implements member functions like void delAllNode (const node), and, void delAllEdge (const edge).

  //delete an edge
  graph->delEdge(e1);

  //delete a node
  graph->delNode(n2);

Following is our graph with node n2 deleted.

6. Printing the graph
The class graph has a friend function which is an overload of the stream operator <<. This function will print the graph (only nodes and edges) in an output stream (here, the standard output, "cout"), in the tulip format.

  //print the result on the standard output
  cout << graph << flush;

7. Saving a graph
Instead of having our graph printed on the standard output, we can save it in a .tlp (tulip format) suffixed file that can be read by tulip :

  //Save  the graph :
  tlp::saveGraph(graph,"tuto1.tlp");

8. Graph deletion
Before exiting the main function, do not forget memory leaks, and delete the graph to free memory usages.

  //delete the graph
  delete graph;
  return EXIT_SUCCESS;
}

9. Compiling and running the program.
Compile this program with this command :
g++ `tulip-config --libs --cxxflags` tutorial.cpp -o tutorial001
Run it to have a look :
./tutorial001

10. Source Code

#include <iostream>
#include <tulip/Graph.h>

/**
 *
 * Tutorial 001
 *
 * Create a graph 
 * add three nodes and three edges
 * remove an edge and a node
 * print the result on the standard output
 * 
 */

using namespace std;
using namespace tlp;

int main() {
  //create an empty graph
  Graph *graph = tlp::newGraph();

  //add three nodes
  node n1 = graph->addNode();
  node n2 = graph->addNode();
  node n3 = graph->addNode();

  //add three edges
  edge e1 = graph->addEdge(n2,n3);
  edge e2 = graph->addEdge(n1,n2);
  edge e3 = graph->addEdge(n3,n1);

  //delete an edge
  graph->delEdge(e1);

  //delete a node
  graph->delNode(n2);

  //print the result on the standard output
  cout << graph << flush ;

  tlp::saveGraph(graph,"tuto1.tlp");

  //delete the graph
  delete graph;
  return EXIT_SUCCESS;
}

TUTORIAL 002 : Iterating over a graph (class Iterator and the macro forEach)
In this tutorial, we will, display on the standard output, all the structure using iterators. For each node, we will display its ancestors, successors, neighbors, and, its incoming and outgoing edges.
In this tutorial, the graph created is the same that in Tutorial 1 (after the 3 edges were added) see the following picture :

1. Header files (Same as Tutorial 1)
Let's start with the files we need to include :

#include <iostream>
#include <tulip/Graph.h>

iostream : This "file" contains the C++ standard declarations for in and out streams. We need it in this tutorial to print the final graph on the standard output.
tulip/Graph.h : This file is the core of the tulip graph API. It provides declarations for graphs (edges , nodes) and functions to load one from a file, to save one, and a lot more. You can find a list in the doxygen documentation.
As you can see, we just need the "Graph.h" header file to create a graph and iterate over its nodes, even though the declaration of the abstract class "Iterator" is in Iterator.h

2. Iterating over all nodes
To iterate over all nodes, we need to create an Iterator on the graph nodes with the member function Iterator* Graph::getNodes () const, we will make it point on the graphs nodes.

  Iterator<node> *itNodes = graph->getNodes();

The documentation of the interface Iterator can be found here.
With the functions template <class itType > bool tlp::Iterator< itType >::hasNext ( ) and node next ( ), we can iterate through our graph nodes with a simple while :

   while(itNodes->hasNext()) {
   	node n = itNodes->next();

In this while loop, we display some node topological properties :

    cout << "node: " <<  n.id << endl;
    cout << " degree: " << graph->deg(n) << endl;
    cout << " in-degree: " << graph->indeg(n) << endl;
    cout << " out-degree: " << graph->outdeg(n) << endl;

At the end of the loop, we will need to delete the iterator: delete itNodes;
Following is the output of this simple while loop :

[root@atlas tutorial-002]# ./tutorial002
node: 0
 degree: 2
 in-degree: 1
 out-degree: 1
node: 1
 degree: 2
 in-degree: 1
 out-degree: 1
node: 2
 degree: 2
 in-degree: 1
 out-degree: 1

3. Iterating through a node predecessors
To iterate through predecessors of node, we use the same type of Iterator, but, instead of using the function getNodes() of the class Graph, we will use the function Iterator<node>* getInNodes (const node) const that will return an iterator on the predecessors of a node.

    //===========================
    //iterate all predecessors of a node
    cout << " predecessors: {";
    Iterator<node> *itN=graph->getInNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

4. Iterating through a node successors
To iterate through successors of a node, we just need to use the function Iterator<node>* Graph::getOutNodes (const node) const to have an Iterator on its successors.

    //===========================
    //iterate all successors of a node
    cout << " successors: {";
    itN = graph->getOutNodes(n);
    while (itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

5. Iterating through a node neighbors (predecessors and successors)
For neighbors, we will use the function Iterator<node>* Graph::getInOutNodes (const node) const to have an Iterator on its neighbors.

    //===========================
    //iterate the neighborhood of a node
    cout << " neighborhood: {";
    itN = graph->getInOutNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

6. Iterating through a node incoming edges
For incoming edges, we will use an Iterator on edges with the member function Iterator<edge>* Graph::getInEdges (const node) const.

   //===========================
    //iterate the incoming edges
    cout << " incoming edges: {";
    Iterator<edge> *itE=graph->getInEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;
    cout << " outcoming edges: {";

7. Iterating through a node outgoing edges
For outgoing edges, we will use the function Iterator<edge>* Graph::getOutEdges (const node) const.

     //===========================
    //iterate the outcomming edges
    itE = graph->getOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

8. Iterating through a node adjacent edges
For adjacent edges, we will use the function Iterator<edge>* Graph::getInOutEdges (const node) const.

    //===========================
    //iterate the adjacent edges
    cout << " adjacent edges: {";
    itE = graph->getInOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

Don't forget memory leaks
As we are still in the first while (iterating through all nodes) we need to delete the Iterator on Nodes :

}// end while 
delete itNodes; //!!!Warning : do not forget to delete iterators (memory leak)

9. Iterating on edges (all edges).
Some times it can be useful to iterate on edges, for example in the algorithm of Kruskal. That is why the graph class owns the function Iterator<edge>* Graph::getEdges (const node) const, that return a pointer on an Iterator of type edge. Following is an exemple of its use.

  //===========================
  //Iterate all edges
  Iterator<edge> *itEdges=graph->getEdges();
  while(itEdges->hasNext()) {
    edge e = itEdges->next();
    cout << "edge: " << e.id;
    cout << " source: " << graph->source(e).id;
    cout << " target: " << graph->target(e).id;
    cout << endl;
  } delete itEdges; //!!!Warning : do not forget to delete iterators (memory leak)

10. The forEach Macro
To simplify the use of Iterators, the API of tulip provides a macro forEach which is quite similar to the foreach of C# or Java. It takes two parameters :
A variable :
An Iterator for the same type as the variable, for example : Variable of type node, Graph::getNodes().
Must use breakForEach to break iteration
Must use returnForEach to return during iteration
This macro function is defined in the header file : tulip/ForEach.h
Following is a small example of its use.

#include <tulip/ForEach.h>

  //...
  //main
  //load Graph 
  //... 
  
  node n = graph->getOneNode();	
  cout << "In Edges :" << endl;		
  edge e;
  forEach(e, graph->getInEdges(n))
  {
    cout << e.id << ",";
  }
  
  //...

Source Code

#include <iostream>
#include <tulip/Graph.h>

/**
 * Tutorial 002
 *
 * Create a graph 
 * display all the structure using iterators
 *
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  //add three edges
  graph->addEdge(n1,n2);
  graph->addEdge(n0,n1);
  graph->addEdge(n2,n0);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);
  
  //===========================
  //Iterate all nodes and display the structure
  Iterator<node> *itNodes = graph->getNodes();
  while(itNodes->hasNext()) {
    node n = itNodes->next();
    cout << "node: " <<  n.id << endl;
    cout << " degree: " << graph->deg(n) << endl;
    cout << " in-degree: " << graph->indeg(n) << endl;
    cout << " out-degree: " << graph->outdeg(n) << endl;

    //===========================
    //iterate all ancestors of a node
    cout << " ancestors: {";
    Iterator<node> *itN=graph->getInNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate all successors of a node
    cout << " successors: {";
    itN = graph->getOutNodes(n);
    while (itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the neighborhood of a node
    cout << " neighborhood: {";
    itN = graph->getInOutNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the incoming edges
    cout << " incoming edges: {";
    Iterator<edge> *itE=graph->getInEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;
    cout << " outcoming edges: {";

    //===========================
    //iterate the outcomming edges
    itE = graph->getOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the adjacent edges
    cout << " adjacent edges: {";
    itE = graph->getInOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

  } delete itNodes; //!!!Warning : do not forget to delete iterators (memory leak)

  //===========================
  //Iterate all edges
  Iterator<edge> *itEdges=graph->getEdges();
  while(itEdges->hasNext()) {
    edge e = itEdges->next(); 
    cout << "edge: " << e.id;
    cout << " source: " << graph->source(e).id;
    cout << " target: " << graph->target(e).id;
    cout << endl;
  } delete itEdges; //!!!Warning : do not forget to delete iterators (memory leak)

  delete graph; //delete the entire graph
  return EXIT_SUCCESS;
}

TUTORIAL 003 : Properties
This tutorial will show you how to add / create properties to a Graph. For local or inherited properties, see tututorial 005. An instance of a property is owned by a graph and is an association table between the elements of graph (nodes and edges) and values of a predefined type.

1. Header files and predefined properties
In tulip API, every type of property is declared in its own header file. Following is a list of those header files and the type of value which can be associated to an element of the graph:
DoubleProperty : tulip/DoubleProperty.h / value type for edge = double, node = double
BooleanProperty : tulip/BooleanProperty.h / value type for edge = bool, node = bool
IntegerProperty: tulip/IntegerProperty.h / value type for edge = int, node = int
LayoutProperty : tulip/LayoutProperty.h / value type for edge = Coord(), node = vector<Coord>()
ColorProperty : tulip/ColorProperty.h / value type for edge = Color(), node = Color()
SizeProperty : tulip/SizeProperty.h / value type for edge = Size(), node = Size()
StringProperty : tulip/StringProperty.h / value type for edge = string, node = string
GraphProperty : tulip/GraphProperty.h / value type for edge = graph, node = graph

2. Creation of a property.
The creation of a property is accomplished by the function Graph::getLocalProperty<TypeProperty>("name of the property"). This function returns a pointer to a property. The real type of the property is given with the template parameter. If the property of the given name does not yet exists, a new one is created and returned.
Using of delete on that property will cause a segmentation violation (use delLocalProperty instead).
Following is a sample of code that creates 8 properties :

  //Get and create several properties
  DoubleProperty *metric = graph->getLocalProperty<DoubleProperty>("firstMetric");
  BooleanProperty *select = graph->getLocalProperty<BooleanProperty>("firstSelection");
  LayoutProperty *layout = graph->getLocalProperty<LayoutProperty>("firstLayout");
  IntegerProperty *integer = graph->getLocalProperty<IntegerProperty>("firstInteger");
  ColorProperty *colors = graph->getLocalProperty<ColorProperty>("firstColors");
  SizeProperty *sizes = graph->getLocalProperty<SizeProperty>("firstSizes");
  GraphProperty *meta = graph->getLocalProperty<GraphProperty>("firstMeta");
  StringProperty *strings = graph->getLocalProperty<StringProperty>("firstString");

3. Initialize all properties.
One property has to be initialized for both edges and nodes. It is done with the functions setAllNodeValue(value) and setAllEdgeValue(value) which are both member functions of the property.
Following is an example :

  //initialize all the properties
  metric->setAllNodeValue(0.0);
  metric->setAllEdgeValue(0.0);
  select->setAllNodeValue(false);
  select->setAllEdgeValue(false);
  layout->setAllNodeValue(Coord(0,0,0)); //coordinates
  layout->setAllEdgeValue(vector<Coord>());//Vector of bends
  integer->setAllNodeValue(0);
  integer->setAllEdgeValue(0);
  sizes->setAllNodeValue(Size(0,0,0)); //width, height, depth
  sizes->setAllEdgeValue(Size(0,0,0)); //start_size, end_size, arrow_size
  colors->setAllNodeValue(Color(0,0,0,0));//Red, green, blue, alpha
  colors->setAllEdgeValue(Color(0,0,0,0));//Red, green, blue, alpha
  strings->setAllNodeValue("first");
  strings->setAllEdgeValue("first");
  meta->setAllNodeValue(graph); //an existing graph

Following is the display (in the tulip GUI) of the list of a node associated values for the properties previously created :

4. Iterating over properties.
Once again, iteration is made with Iterators. The class graph has a member function Iterator< std::string >* getLocalProperties () that returns an iterator on the local properties.
Following is an example :

  cout << "List of the properties present in the graph:" << endl;
  Iterator<string> *it=graph->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

You can also use the macro forEach.

Source Code

#include <iostream>
#include <tulip/BooleanProperty.h>
#include <tulip/ColorProperty.h>
#include <tulip/DoubleProperty.h>
#include <tulip/GraphProperty.h>
#include <tulip/IntegerProperty.h>
#include <tulip/LayoutProperty.h>
#include <tulip/SizeProperty.h>
#include <tulip/StringProperty.h>

/**
 * Tutorial 003
 *
 * Create a graph and a properties of each type
 * And display properties present in the graph
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();
  //build the graph
  buildGraph(graph);

  //Get and create several properties
  DoubleProperty *metric=graph->getLocalProperty<DoubleProperty>("firstMetric");
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  LayoutProperty *layout=graph->getLocalProperty<LayoutProperty>("firstLayout");
  IntegerProperty *integer=graph->getLocalProperty<IntegerProperty>("firstInteger");
  ColorProperty *colors=graph->getLocalProperty<ColorProperty>("firstColors");
  SizeProperty *sizes=graph->getLocalProperty<SizeProperty>("firstSizes");
  GraphProperty *meta=graph->getLocalProperty<GraphProperty>("firstMeta");
  StringProperty *strings=graph->getLocalProperty<StringProperty>("firstString");

  //initialize all the properties
  metric->setAllNodeValue(0.0);
  metric->setAllEdgeValue(0.0);
  select->setAllNodeValue(false);
  select->setAllEdgeValue(false);
  layout->setAllNodeValue(Coord(0,0,0)); //coordinates
  layout->setAllEdgeValue(vector<Coord>());//Vector of bends
  integer->setAllNodeValue(0);
  integer->setAllEdgeValue(0);
  sizes->setAllNodeValue(Size(0,0,0)); //width, height, depth
  sizes->setAllEdgeValue(Size(0,0,0)); //start_size, end_size, arrow_size
  colors->setAllNodeValue(Color(0,0,0,0));//Red, green, blue
  colors->setAllEdgeValue(Color(0,0,0,0));//Red, green, blue
  strings->setAllNodeValue("first");
  strings->setAllEdgeValue("first");
  meta->setAllNodeValue(graph); //an existing graph
  cout << "List of the properties present in the graph:" << endl;
  Iterator<string> *it=graph->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  tlp::saveGraph (graph, "tutoproper.tlp");  
  delete graph;
  return EXIT_SUCCESS;
}

TUTORIAL 004 : Create your first subgraph.
This tutorial will teach you how to create subgraphs. At the end of it, we will have a hierarchy of 3 graphs.
Before anything consider the following function that creates 3 nodes and 3 edges (same as in tutorial 001 ):

void buildGraph(Graph *graph) 
{
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

The creation of a subgraph is quite simple. You just have to use the function Graph* addSubGraph (BooleanProperty* selection = 0) . It will create and return a new SubGraph of the graph. The elements of the new subgraph are those selected in the selection(selection associated value equals true); if there is no selection an empty subgraph is returned.
In the following sample we create 3 empty subgraphs :

  //build three empty subgraphs
  Graph *subgraph0=graph->addSubGraph();
  Graph *subgraph1=graph->addSubGraph();
  Graph *subgraph2=subgraph1->addSubGraph();

We now need to create some nodes and edges :

   //add node inside subgraphs
  buildGraph(subgraph0);
  buildGraph(subgraph1);
  buildGraph(subgraph2);

Following is the hierarchy we have just created, displayed with tulip :
We can check that by iterating on our graph's subgraphs using the function Iterator< Graph * >* Graph::getSubGraphs() :

  //iterate subgraph (0 and 1 normally ) and output them
  Iterator<Graph *> *itS=graph->getSubGraphs();
  while (itS->hasNext())
    cout << itS->next() << endl;
  delete itS;

Source Code

#include <iostream>
#include <tulip/Graph.h>

/**
 * Tutorial 004
 *
 * Create a graph and three subgraphs,
 * display all the structure using iterators
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //build two empty subgraph
  Graph *subgraph0=graph->addSubGraph();
  Graph *subgraph1=graph->addSubGraph();
  Graph *subgraph2=subgraph1->addSubGraph();

  //add node inside subgraphs
  buildGraph(subgraph0);
  buildGraph(subgraph1);
  buildGraph(subgraph2);

  //iterate subgraph (0 and 1 normally ) and output them
  Iterator<Graph *> *itS=graph->getSubGraphs();
  while (itS->hasNext()) 
    cout << itS->next() << endl;
  delete itS;

  delete graph;
  return EXIT_SUCCESS;
}

TUTORIAL 005 : Properties and subgraphs
In this tutorial, we will show you how to use properties with subgraphs, how to deal with properties in a big hierarchy. To do so, we will create a graph with some properties, several subgraphs with other properties and iterate over local and inherited properties.

1. Introduction
We will first begin with the creation of the graph and its properties :

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //Get and create several properties
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  graph->getLocalProperty<ColorProperty>("firstColors");
  graph->getLocalProperty<DoubleProperty>("firstMetric");

  //init the selection in order to use it for building clone subgraph
  select->setAllNodeValue(true);
  select->setAllEdgeValue(true);

The function void buildGraph(Graph *g), is the one implemented in Tutorial 004.
In the sample of code above, we create a graph with 3 properties : firstSelection (select), fisrtColors and firstMetric. We then set all nodes and edges "firstSelection" associated value to true which means that all nodes and edges are selected.
We, then, create two subgraphs out of our selection (the entire graph) :

  //Create a hierarchy of subgraph (they all own the same elements)
  Graph *subgraph1=graph->addSubGraph(select);
  Graph *subgraph2=subgraph1->addSubGraph(select);

And, to finish this section, we add some new properties to those two subgraphs :

   //create a property in subgraph1 (redefinition of the one defined in graph)
  subgraph1->getLocalProperty<DoubleProperty>("firstMetric");

  //create a new property in subgraph1
  subgraph1->getLocalProperty<DoubleProperty>("secondMetric");

  //create a new property in subgraph3
  subgraph2->getLocalProperty<DoubleProperty>("thirdMetric");

The property "firstMetric" will be redefined but not the two other ones.

2. Properties of subgraph1
A good way to see what we have created is to iterate over the local properties of subgraph1 and in a second time iterate over inherited properties.
Following is a sample and its output that enables the iteration over local properties :

  cout << "List of the local properties present in the subgraph1:" << endl;   
  Iterator<string> *it=subgraph1->getLocalProperties();    		    
  while (it->hasNext()) {                                 		    
    cout << it->next() << endl;                                           
  } delete it;          
  
  
_________________________________________________________________________  

 
[root@atlas tutorial-005]# ./tutorial 
List of the local properties present in the subgraph1:
firstMetric	
secondMetric

As you can see the only local properties that has subgraph1 are "firstMetric" and "secondMetric". Indeed, "firstMetric" has been redefined, and, "thirdMetric" has been created with subgraph2.
Following is a sample and its output that enables the iteration over inherited properties :

  cout << "List of the inherited properties present in the subgraph1:" << endl;  
  it=subgraph1->getInheritedProperties();                        		        
  while (it->hasNext()) {                                 		        
    cout << it->next() << endl;                                               
  } delete it;                                                                
  
_________________________________________________________________________  

 List of the local properties present in the subgraph1:  
   firstColors       		
   firstSelection

As you can see, subgraph1 just has two inherited properties since "firstMetric" has been redefined.
Following is a sample of code that lists all the properties of a graph, the inherited properties and local properties :

  cout << "List of properties present in the subgraph1:" << endl;
  it=subgraph1->getProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;
  
_________________________________________________________________________    
  
List of properties present in the subgraph1:
firstMetric
secondMetric
firstColors
firstSelection

3. Properties of subgraph2
As we did with subgraph1, we will now iterate over the local properties of subgraph2 in a first time and in a second time iterate over its inherited properties.
Following is a sample and its output that enables the iteration over local properties :

  cout << "List of the local properties present in the subgraph2:" << endl;  
  it=subgraph2->getLocalProperties();    		                            
  while (it->hasNext()) {                                 		    
    cout << it->next() << endl;                                           
   } delete it;                                                            

_________________________________________________________________________

[root@atlas tutorial-005]# ./tutorial
 List of the local properties present in the subgraph2:
 thirdMetric

The only local properties that has subgraph1 is thirdMetric.
Following is a sample and its output that enables the iteration over inherited properties :

  cout << "List of the inherited properties present in the subgraph2:" << endl;   
  it=subgraph2->getInheritedProperties();                        		        
  while (it->hasNext()) {                                 		        
    cout << it->next() << endl;                                                 
  } delete it;                                                                        		
      		
_________________________________________________________________________ 
      		
List of the local properties present in the subgraph2:      		
firstColors     		
firstMetric     		
firstSelection      		
secondMetric

As you can see, subgraph2 has a lot of inherited properties since he is the subgraph of subgraph1 which is the subgraph of the root graph.

Source Code

#include <iostream>
#include <tulip/BooleanProperty.h>
#include <tulip/ColorProperty.h>
#include <tulip/DoubleProperty.h>

/**
 * Tutorial 005
 *
 * Create a graph hierarchy with several properties
 * Display the inherited and local properties in each graph
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //Get and create several properties
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  graph->getLocalProperty<ColorProperty>("firstColors");
  graph->getLocalProperty<DoubleProperty>("firstMetric");

  //init the selection in order to use it for building clone subgraph
  select->setAllNodeValue(true);
  select->setAllEdgeValue(true);

  //Create a hierarchy of subgraph (there are all the same)
  Graph *subgraph1=graph->addSubGraph(select);
  Graph *subgraph2=subgraph1->addSubGraph(select);

  //create a property in subgraph1 (redefinition of the one defined in graph)
  subgraph1->getLocalProperty<DoubleProperty>("firstMetric");

  //create a new property in subgraph1
  subgraph1->getLocalProperty<DoubleProperty>("secondMetric");

  //create a new property in subgraph3
  subgraph2->getLocalProperty<DoubleProperty>("thirdMetric");

  cout << "List of the local properties present in the subgraph1:" << endl;
  Iterator<string> *it=subgraph1->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  cout << "List of inherited properties present in the subgraph1:" << endl;
  it=subgraph1->getInheritedProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;


  cout << "List of properties present in the subgraph1:" << endl;
  it=subgraph1->getProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;


  cout << "List of the local properties present in the subgraph2:" << endl;
  it=subgraph2->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  cout << "List of inherited properties present in the subgraph2:" << endl;
  it=subgraph2->getInheritedProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  delete graph;
  return EXIT_SUCCESS;
}

TUTORIAL 006 : Edges order.
In this tutorial, we will learn how to change edges order in the graph edges adjacency list (please visit Wikipedia: Adjacency and degree for more details ). Indeed, it can be useful to sort the edges considering a metric.

1. Creation of the graph and its edges
We will create a graph with 4 nodes and 4 edges. Their "id number" will start from 0 just like in the figure below :
Following is the sample of code that created such a graph:

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();

  //add three edges
  edge e0=graph->addEdge(n1,n2);
  edge e1=graph->addEdge(n0,n1);
  edge e2=graph->addEdge(n2,n0);
  edge e3=graph->addEdge(n3,n0);

As you can see, node 0 has three edges : edge 1,edge 2 and edge 3. And if we display its edges adjacency list (see last section for function void displayAdjacency(node n, Graph *graph) ) we obtain the following output :

 1 2 3

2. Swap edges
Swapping edges can be easily done with the function, void Graph::swapEdgeOrder ( const node, const edge,const edge) that will, as said swap two edges in the adjacent list of a node. Following is an example of its use :

  //swap e1 and e3
  graph->swapEdgeOrder(n0, e1, e3);

As you can see, the adjacency list has changed :

  3 2 1

3. Setting an order
An other way to change the edges order is to use a vector of type edge and the function : void Graph::setEdgeOrder (const node, const std::vector < edge > ), following is an example that will replace e1 and e3 in their original order :

  vector<edge> tmp(2);
  tmp[0]=e1;
  tmp[1]=e3;
  graph->setEdgeOrder(n0,tmp);

And the new order :

  1 2 3

Source Code

#include <iostream>
#include <tulip/Graph.h>
#include <tulip/MutableContainer.h>

/**
 * Tutorial 006
 *
 * Create a graph
 * Order the edges around the nodes
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  //add three edges
  graph->addEdge(n1,n2);
  graph->addEdge(n0,n1);
  graph->addEdge(n2,n0);
}

void displayAdjacency(node n, Graph *graph) {
  Iterator<edge>*ite=graph->getInOutEdges(n);
  while(ite->hasNext())
    cout << ite->next().id << " ";
  delete ite;
  cout << endl;
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();

  //add three edges
  edge e0=graph->addEdge(n1,n2);
  edge e1=graph->addEdge(n0,n1);
  edge e2=graph->addEdge(n2,n0);
  edge e3=graph->addEdge(n3,n0);

  tlp::saveGraph(graph, "adj1.tlp");

  //display current order of edge around n1
  displayAdjacency(n0,graph);
  
  //swap e1 and e3
  graph->swapEdgeOrder(n0,e1,e3);
  

  //display the new order of edge around n1
  displayAdjacency(n0,graph);

  vector<edge> tmp(2);
  tmp[0]=e1;
  tmp[1]=e3;
  graph->setEdgeOrder(n0,tmp);
  //display the new order of edge around n1
  displayAdjacency(n0,graph);
  delete graph;
  return EXIT_SUCCESS;
}

TUTORIAL 007 : Mutable Collection
In this small tutorial, we will learn how to use the Mutable Container (an efficient associative container) of the tulip API that enables :
A tradeoff between speed and memory.
To manage fragmented index
The direct access in this container is forbidden, but it exist a getter and a setter :
const ReturnType<TYPE >::ConstValue MutableContainer<type>::get(const unsigned int i) const that returns a reference instead of a copy in order to minimize the number copy of objects, user must be aware that calling the set function can devalidate this reference
void MutableContainer<type>::set( const unsigned int i,const TYPE value).
The MutableContainer has two more methods :
void setAll (const TYPE value)
IteratorValue* findAll(const TYPE &value, bool equal = true) const
Following is a small example of its use :

  //declaration of a new MutableContainer 
  MutableContainer<int> t;
  
  //set all element to 0
  t.setAll(0);
  //except element of index 1 set to 1.
  t.set(1,1);
  
  //display on standard output
  cout << t.get(1) << "and" << t.get(2) << endl;

TUTORIAL 008 : Graph Tests
The tulip API has special functions to test if a graph is element of a specific class of graph. Moreover results are buffered and automatically updated if it is possible in constant time.
Specific functions are available for each test.
Each class of graph has its own header file. Following is a list of those header files and an example of their use :
tulip/AcyclicTest.h

 AcyclicTest::isAcyclic(graph);

tulip/BiconnectedTest.h

 BiconnectedTest::isBiconnected(graph);

tulip/ConnectedTest.h

 ConnectedTest::isConnected(graph);

tulip/OuterPlanarTest.h

 PlanarityTest::isOuterPlanar(graph);

tulip/PlanarityTest.h

 PlanarityTest::isPlanar(graph);

tulip/SimpleTest.h

 SimpleTest::isSimple(graph);

tulip/TreeTest.h

  TreeTest::isTree(graph);

tulip/TriconnectedTest.h

 TriconnectedTest::isTriconnected(graph);

TUTORIAL 009 : ObservableGraph
In this tutorial, we will show you how to use the class ObservableGraph that enables to receive notification when a graph is updated.
First, we will create a class that inherits from ObservableGraph, and then use it and see what this new class is able to "do".

1. Our new class, GraphObserverTest :
Header files and namespaces :
To continue this tutorial, we need to include the following files, and namespaces.

#include <iostream>
#include <set>
//- - - - - - - - - - - - -
#include <tulip/TlpTools.h>
#include <tulip/Graph.h>
#include <tulip/ObservableGraph.h>
//- - - - - - - - - - - - -

using namespace std;
using namespace tlp;

As said before, we will create a new class that inherits from ObservableGraph. This class will have several functions to be notified when a node or an edge is deleted or added or reversed (edge).
Following is the class GraphObserverTest :

class GraphObserverTest : public GraphObserver {
public:
  GraphObserverTest() {
  }

private:
  void addEdge(Graph * g,const edge e) {
    cout << "edge :" << e.id << " has been added" << endl;
  }
  void delEdge(Graph *,const edge e) {
    cout << "edge :" << e.id << " is about to be deleted" << endl;
  }
  void reverseEdge(Graph *,const edge e) {
    cout << "edge :" << e.id << " is about to be reversed" << endl;
  }
  void addNode(Graph * g,const node n) {
    cout << "node :" << n.id << " has been added" << endl;
  }
  void delNode(Graph *,const node n) {
    cout << "node :" << n.id << " is about to be deleted" << endl;
  }
  void destroy(Graph *g) {
    cout << "graph : " << g->getId() << " is about to be deleted" << endl;
  }
};

Those methods are redefinitions of their homologues in the super class.

2. The Main function
Following in the main function with some explanations :

int main(int argc, char **argv) {
  Graph *graph = tlp::newGraph();

Nothing really new here, just the creation of the graph.

  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  GraphObserverTest graphObserverTest;
  graph->addGraphObserver(&graphObserverTest);
  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

We add the instance of our class GraphObserverTest with the function Graph::addObserver .
We then perform some modifications on the graph :

  node n1 = graph->addNode();
  node n0 = graph->addNode();
  edge e0  = graph->addEdge(n0, n1);
  graph->reverse(e0);
  graph->delNode(n0);
  delete graph;
  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  return EXIT_SUCCESS;
}

Following is the output of this program :

node :0 has been added
node :1 has been added
edge :0 has been added
edge :0 is about to be reversed
node :0 is about to be deleted 
edge :0 is about to be deleted