<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY igraph "igraph">
]>

<chapter id="igraph-Tutorial">
<title>Tutorial</title>

<section id="tut-lesson-1"><title>Compiling programs using igraph</title>

<para>
The following short example program demonstrates the basic usage of
the <command>igraph</command> library. Save it into a file named
<filename>igraph_test.c</filename>.
<xi:include href="../examples/tutorial/tutorial1.c.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</para>

<para>
This example illustrates a couple of points:
</para>

<itemizedlist>
<listitem><para>
First, programs
using the <command>igraph</command> library should include the
<filename>igraph.h</filename> header
file. Note that while igraph installs several sub-headers, the organization of these may change
without notice. Only use <filename>igraph.h</filename> in your projects, not any of the sub-headers.
</para></listitem>
<listitem><para>
Second, the library must be initialized using
<link linkend="igraph_setup"><function>igraph_setup()</function></link>
before use.
</para></listitem>
<listitem><para>
Third, <command>igraph</command> uses the
<type>igraph_int_t</type> type for integers instead of
<type>int</type> or <type>long int</type>, and it also uses the
<type>igraph_real_t</type> type for real numbers instead of
<type>double</type>. Depending on how <command>igraph</command> was compiled, and whether you are
using a 32-bit or 64-bit system, <type>igraph_int_t</type> may be a 32-bit
or 64-bit integer.
</para></listitem>
<listitem><para>
Fourth, <command>igraph</command> graph objects are represented by the <type>igraph_t</type> data
type.
</para></listitem>
<listitem><para>
Fifth, the <link
linkend="igraph_erdos_renyi_game_gnm"><function>igraph_erdos_renyi_game_gnm()</function></link>
creates a graph and <link
linkend="igraph_destroy"><function>igraph_destroy()</function></link>
destroys it, i.e. deallocates the memory associated to it.
</para></listitem>
</itemizedlist>

<para>
For compiling this program you need a C compiler. Optionally,
<ulink url="https://cmake.org">CMake</ulink> can be used to automate the compilation.
</para>

<section id="tut-lesson-1-compiling-with-cmake">
<title>Compiling with CMake</title>

<para>
It is convenient to use CMake because it can automatically discover the
necessary compilation flags on all operating systems. Many IDEs support
CMake, and can work with CMake projects directly. To create a CMake project
for this example program, create a file name <filename>CMakeLists.txt</filename> with the
following contents:

<programlisting>
cmake_minimum_required(VERSION 3.18)
project(igraph_test)

find_package(igraph REQUIRED)

add_executable(igraph_test igraph_test.c)
target_link_libraries(igraph_test PUBLIC igraph::igraph)
</programlisting>
</para>

<para>
To compile the project, create a new directory called <filename>build</filename> in
the root of the <command>igraph</command> source tree, and switch to it:
<programlisting>
mkdir build
cd build
</programlisting>
</para>

<para>
Run CMake to configure the project:
<programlisting>
cmake ..
</programlisting>
</para>

<para>
If <command>igraph</command> was installed at a non-standard location, specify its prefix
using the <option>-DCMAKE_PREFIX_PATH=...</option> option. The prefix must be
the same directory that was specified as the <option>CMAKE_INSTALL_PREFIX</option>
when compiling igraph.
</para>

<para>
If configuration has succeeded, build the program using
<programlisting>
cmake --build .
</programlisting>
</para>

<note><title>C++ must be enabled in igraph projects</title>
<para>Parts of <command>igraph</command> are implemented in C++; therefore, any CMake target that
depends on <command>igraph</command> should use the C++ linker. Furthermore, OpenMP support in
igraph works correctly only if C++ is enabled in the CMake project. The script
that finds <command>igraph</command> on the host machine will throw an error if C++ support is
not enabled in the CMake project.</para>

<para>C++ support is enabled by default when no languages are explicitly
specified in CMake's <ulink url="https://cmake.org/cmake/help/latest/command/project.html"><code>project</code></ulink>
command, e.g. <code>project(igraph_test)</code>. If you do specify some languages explicitly,
make sure to also include <code>CXX</code>, e.g. <code>project(igraph_test C CXX)</code>.
</para>
</note>

</section>

<section id="tut-lesson-1-compiling-without-cmake">
<title>Compiling without CMake</title>

<para>
On most Unix-like systems, the default C compiler is called <command>cc</command>.
To compile the test program, you will need a command similar to the following:
<programlisting>
cc igraph_test.c -I/usr/local/include/igraph -L/usr/local/lib -ligraph -o igraph_test
</programlisting>
</para>

<para>
The exact form depends on where <command>igraph</command> was installed on your
system, whether it was compiled as a shared or static library, and the external
libraries it was linked to. The directory after the <option>-I</option> switch
is the one containing the <filename>igraph.h</filename> file, while the one
following <option>-L</option> should contain the library file itself, usually a
file called <filename>libigraph.a</filename> (static library on macOS and
Linux), <filename>libigraph.so</filename> (shared library on Linux),
<filename>libigraph.dylib</filename> (shared library on macOS),
<filename>igraph.lib</filename> (static library on Windows) or
<filename>igraph.dll</filename> (shared library on Windows). If
<command>igraph</command> was compiled as a static library, it is also
necessary to manually link to all of its dependencies.
</para>

<para>
If your system has the <command>pkg-config</command> utility you are
likely to get the necessary compile options by issuing the command
<programlisting>
pkg-config --libs --cflags igraph
</programlisting>
(if <command>igraph</command> was built as a shared library) or
<programlisting>
pkg-config --static --libs --cflags igraph
</programlisting>
(if <command>igraph</command> was built as a static library).
</para>

</section>

<section id="tut-lesson-1-running-the-program">
<title>Running the program</title>

<para>
On most systems, the executable can be run by simply typing its name like this:
<programlisting>
./igraph_test
</programlisting>
If you use dynamic linking and the <command>igraph</command>
library is not installed in a standard place, you may need to add its location to the
<envar>LD_LIBRARY_PATH</envar> (Linux), <envar>DYLD_LIBRARY_PATH</envar> (macOS)
or <envar>PATH</envar> (Windows) environment variables. This is typically necessary
on Windows systems.
</para>

</section>

</section>
<section id="tut-lesson-2"><title>Creating your first graphs</title>

<para>
The functions generating graph objects are called graph
generators. Stochastic (i.e. randomized) graph generators are called
<quote>games</quote>.
</para>

<para>
<command>igraph</command> can handle directed and undirected graphs. Most graph
generators are able to create both types of graphs and most other
functions are usually also capable of handling
both. E.g., <link linkend="igraph_get_shortest_paths"><function>igraph_get_shortest_paths()</function></link>,
which calculates shortest paths from a vertex to other vertices, can calculate
directed or undirected paths.
</para>

<para>
<command>igraph</command> has sophisticated ways for creating graphs. The simplest
graphs are deterministic regular structures like star graphs
(<link linkend="igraph_star"><function>igraph_star()</function></link>),
cycle graphs (<link linkend="igraph_cycle_graph"><function>igraph_cycle_graph()</function></link>), lattices
(<link linkend="igraph_square_lattice"><function>igraph_square_lattice()</function></link>) or trees
(<link linkend="igraph_kary_tree"><function>igraph_kary_tree()</function></link>), and many more.
</para>

<para>
The following example creates an undirected regular circular lattice,
adds some random edges to it and calculates the average length of
shortest paths between all pairs of vertices in the graph before and
after adding the random edges. (The message is that some random edges
can reduce path lengths a lot.)
<xi:include href="../examples/tutorial/tutorial2.c.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</para>

<para>
This example illustrates some new points. <command>igraph</command> uses
<link linkend="igraph_vector_t"><type>igraph_vector_t</type></link>
and its related types (<type>igraph_vector_int_t</type>, <type>igraph_vector_bool_t</type>
and so on) instead of plain C arrays. <type>igraph_vector_t</type> is superior to
regular arrays in almost every sense. Vectors are created by the
<link linkend="igraph_vector_init"><function>igraph_vector_init()</function></link>
function and, like graphs, they should be destroyed if not
needed any more by calling
<link linkend="igraph_vector_destroy"><function>igraph_vector_destroy()</function></link>
on them. A vector can be indexed by the
<link linkend="VECTOR"><function>VECTOR()</function></link> function
(right now it is a macro). The elements of a vector are of type <type>igraph_real_t</type>
for <link linkend="igraph_vector_t"><type>igraph_vector_t</type></link>,
and of type <type>igraph_int_t</type> for <type>igraph_vector_int_t</type>.
As you might expect, <type>igraph_vector_bool_t</type> holds
<type>igraph_bool_t</type> values. Vectors can be resized and most <command>igraph</command>
functions returning the result in a vector automatically resize it to the size they need.
</para>

<para>
<link linkend="igraph_square_lattice"><function>igraph_square_lattice()</function></link>
takes an integer vector argument specifying the dimensions of
the lattice. In this example we generate a 30x30 two dimensional
periodic lattice. See the documentation of
<link linkend="igraph_square_lattice"><function>igraph_square_lattice()</function></link> in
the reference manual for the other arguments.
</para>

<para>
The vertices in a graph are identified by a <emphasis>vertex ID</emphasis>, an integer between
<code>0</code> and <code>n - 1</code>, where <code>n</code> is the number of vertices in the graph.
The vertex count can be retrieved using <link linkend="igraph_vcount"><function>igraph_vcount()</function></link>,
as in the example.
</para>

<para>
The <link linkend="igraph_add_edges"><function>igraph_add_edges()</function></link>
function simply takes a graph and a vector of
vertex IDs defining the new edges. The first edge is between the first
two vertex IDs in the vector, the second edge is between the second
two, etc. This way we add ten random edges to the lattice.
</para>

<para>
Note that this example program may add <emphasis>loop edges</emphasis>, edges
pointing a vertex to itself, or <emphasis>multiple edges</emphasis>, more than one edge
between the same pair of vertices.
<type>igraph_t</type> can of course represent loops and multiple edges, although some
routines expect simple graphs, i.e. graphs which contain neither of these. This is because some
structural properties are ill-defined for non-simple graphs. Loop and multi-edges can be removed by calling
<link linkend="igraph_simplify"><function>igraph_simplify()</function></link>.
</para>

</section>
<section id="tut-lesson-3"><title>Calculating various properties of graphs</title>
<para>
In our next example we will calculate various centrality measures in a
friendship graph. The friendship graph is from the famous Zachary karate
club study. (Do a web search on "Zachary karate" if you want to know more about
this.) Centrality measures quantify how central is the position of
individual vertices in the graph.
<xi:include href="../examples/tutorial/tutorial3.c.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</para>

<para>
This example demonstrates some new operations. First of all, it shows a
way to create a graph a list of edges stored in a plain C array.
Function <link linkend="igraph_vector_view"><function>igraph_vector_view()</function></link>
creates a <emphasis>view</emphasis> of a C array. It does not copy any data,
which means that you must not call
<link linkend="igraph_vector_destroy"><function>igraph_vector_destroy()</function></link>
on a vector created this way. This vector is then used to create the
undirected graph.
</para>

<para>
Then the degree, closeness and betweenness centrality of the vertices
is calculated and the highest values are printed. Note that the vector
<varname>result</varname>, into which these functions will write their
result, must be initialized first, and also that the functions resize
it to be able to hold the result.
</para>

<para>
Notice that in order to print values of type <type>igraph_int_t</type>,
we used the <constant>IGRAPH_PRId</constant> format macro constant. This
macro is similar to the standard <constant>PRI</constant> constants defined
in <code>stdint.h</code>, and expands to the correct <code>printf</code>
format specifier on each platform that <command>igraph</command> supports.
</para>

<para>
The <link linkend="igraph_vss_all"><function>igraph_vss_all()</function></link> argument
tells the functions to calculate the property for every vertex in the graph.
It is shorthand for a <emphasis>vertex selector</emphasis>, represented by type
<type>igraph_vs_t</type>.
Vertex selectors help perform operations on a subset of vertices.
You can read more about them in <link linkend="igraph-Iterators">one
of the following chapters</link>.
</para>
</section>

</chapter>