Abdelrahman Said
242 lines
9.0 KiB
XML
242 lines
9.0 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE chapter 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-Basic">
|
|
<title>Basic data types and interface</title>
|
|
|
|
<section id="igraph-data-model"><title>The &igraph; data model</title>
|
|
<para>
|
|
The &igraph; library can handle directed and
|
|
undirected graphs. The &igraph; graphs are multisets
|
|
of ordered (if directed) or unordered (if undirected) labeled pairs.
|
|
The labels of the pairs plus the number of vertices always starts with
|
|
zero and ends with the number of edges minus one. In addition to that,
|
|
a table of metadata is also attached to every graph, its most
|
|
important entries being the number of vertices in the graph and whether
|
|
the graph is directed or undirected.
|
|
</para>
|
|
|
|
<para>
|
|
Like the edges, the &igraph; vertices are also
|
|
labeled by numbers between zero and the number of vertices minus one.
|
|
So, to summarize, a directed graph can be imagined like this:
|
|
<informalexample>
|
|
<programlisting>
|
|
( vertices: 6,
|
|
directed: yes,
|
|
{
|
|
(0,2),
|
|
(2,2),
|
|
(3,2),
|
|
(3,3),
|
|
(3,4),
|
|
(3,4),
|
|
(4,3),
|
|
(4,1)
|
|
}
|
|
)
|
|
</programlisting>
|
|
</informalexample>
|
|
Here the edges are ordered pairs or vertex ids, and the graph is a multiset
|
|
of edges plus some metadata.
|
|
</para>
|
|
|
|
<para>
|
|
An undirected graph is like this:
|
|
<informalexample>
|
|
<programlisting>
|
|
( vertices: 6,
|
|
directed: no,
|
|
{
|
|
(0,2),
|
|
(2,2),
|
|
(2,3),
|
|
(3,3),
|
|
(3,4),
|
|
(3,4),
|
|
(3,4),
|
|
(1,4)
|
|
}
|
|
)
|
|
</programlisting>
|
|
</informalexample>
|
|
Here, an edge is an unordered pair of two vertex IDs. A graph is a multiset
|
|
of edges plus metadata, just like in the directed case.
|
|
</para>
|
|
|
|
<para>It is possible to convert between directed and undirected graphs,
|
|
see the <link linkend="igraph_to_directed">
|
|
<function>igraph_to_directed()</function></link>
|
|
and <link linkend="igraph_to_undirected">
|
|
<function>igraph_to_undirected()</function></link> functions.
|
|
</para>
|
|
|
|
<para>&igraph; aims to robustly support multigraphs, i.e. graphs which
|
|
have more than one edge between some pairs of vertices, as well as
|
|
graphs with self-loops. Most functions which do not support such graphs
|
|
will check their input and issue an error if it is not valid. Those
|
|
rare functions which do not perform this check clearly indicate this
|
|
in their documentation. To eliminate multiple edges from a graph, you can use
|
|
<link linkend="igraph_simplify">
|
|
<function>igraph_simplify()</function></link>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="igraph-functions"><title>General conventions of &igraph; functions</title>
|
|
<para>
|
|
&igraph; has a simple and consistent interface. Most functions check
|
|
their input for validity and display an informative error message
|
|
when something goes wrong. In order to support this, the majority of functions
|
|
return an error code. In basic usage, this code can be ignored, as the
|
|
default behaviour is to abort the program immediately upon error. See
|
|
<link linkend="igraph-Error">the section on error handling</link> for
|
|
more information on this topic.
|
|
</para>
|
|
|
|
<para>
|
|
Results are typically returned through <emphasis>output arguments</emphasis>,
|
|
i.e. pointers to a data structure into which the result will be written.
|
|
In almost all cases, this data structure is expected to be pre-initialized.
|
|
A few simple functions communicate their result directly through their return
|
|
value—these functions can never encounter an error.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="basic-data-types"><title>Atomic data types</title>
|
|
|
|
<indexterm><primary>igraph_int_t</primary></indexterm>
|
|
|
|
<para>
|
|
&igraph; introduces a few aliases to standard C data types that are then used
|
|
throughout the library. The most important of these types is
|
|
<type>igraph_int_t</type>, which is an alias to either a 32-bit or a 64-bit
|
|
<emphasis>signed</emphasis> integer, depending on whether &igraph; was compiled
|
|
in 32-bit or 64-bit mode. The size of <type>igraph_int_t</type> also
|
|
influences the maximum number of vertices that an &igraph; graph can represent
|
|
as the number of vertices is stored in a variable of type
|
|
<type>igraph_int_t</type>.
|
|
</para>
|
|
|
|
<para>
|
|
Before igraph 1.0, <type>igraph_int_t</type> was called <type>igraph_integer_t</type>.
|
|
This is still available as an alias to <type>igraph_int_t</type> and will remain
|
|
accessible until at least version 2.0 of the library.
|
|
</para>
|
|
|
|
<para>Since the size of a variable of type <type>igraph_int_t</type> may
|
|
change depending on how &igraph; is compiled, you cannot simply use
|
|
<code>%d</code> or <code>%ld</code> as a placeholder for &igraph; integers in
|
|
<code>printf</code> format strings. &igraph; provides the
|
|
<code>IGRAPH_PRId</code> macro, which maps to <code>d</code>, <code>ld</code>
|
|
or <code>lld</code> depending on the size of <type>igraph_int_t</type>, and
|
|
you must use this macro in <code>printf</code> format strings to avoid compiler
|
|
warnings.
|
|
</para>
|
|
|
|
<indexterm><primary>igraph_uint_t</primary></indexterm>
|
|
|
|
<para>Similarly to how <type>igraph_int_t</type> maps to the standard size
|
|
signed integer in the library, <type>igraph_uint_t</type> maps to a 32-bit or
|
|
a 64-bit <emphasis>unsigned</emphasis> integer. It is guaranteed that the size of
|
|
<type>igraph_int_t</type> is the same as the size of <type>igraph_uint_t</type>.
|
|
&igraph; provides <code>IGRAPH_PRIu</code> as a format string placeholder for
|
|
variables of type <type>igraph_uint_t</type>.
|
|
</para>
|
|
|
|
<indexterm><primary>igraph_real_t</primary></indexterm>
|
|
|
|
<para>Real numbers (i.e. quantities that can potentially be fractional or
|
|
infinite) are represented with a type named <type>igraph_real_t</type>. Currently
|
|
<type>igraph_real_t</type> is always aliased to <type>double</type>, but it is
|
|
still good practice to use <type>igraph_real_t</type> in your own code for sake
|
|
of consistency.</para>
|
|
|
|
<indexterm><primary>igraph_bool_t</primary></indexterm>
|
|
|
|
<para>Boolean values are represented with a type named <type>igraph_bool_t</type>.
|
|
It tries to be as small as possible since it only needs to represent a truth
|
|
value. For printing purposes, you can treat it as an integer and use
|
|
<code>%d</code> in format strings as a placeholder for an <type>igraph_bool_t</type>.
|
|
</para>
|
|
|
|
<indexterm><primary>IGRAPH_INTEGER_MAX</primary></indexterm>
|
|
<indexterm><primary>IGRAPH_INTEGER_MIN</primary></indexterm>
|
|
<indexterm><primary>IGRAPH_UINT_MAX</primary></indexterm>
|
|
<indexterm><primary>IGRAPH_UINT_MIN</primary></indexterm>
|
|
<para>
|
|
Upper and lower limits of <type>igraph_int_t</type> and
|
|
<type>igraph_uint_t</type> are provided by the constants named
|
|
<constant>IGRAPH_INTEGER_MIN</constant>, <constant>IGRAPH_INTEGER_MAX</constant>,
|
|
<constant>IGRAPH_UINT_MIN</constant> and <constant>IGRAPH_UINT_MAX</constant>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section><title>Setup and initialization</title>
|
|
<para>
|
|
Certain parts of &igraph; must be initialized before first use, which can be
|
|
accomplished using the setup functions below. As of igraph 1.0, most functions
|
|
will work correctly even if setup is not performed, as currently the only setup
|
|
action is seeding the random number generator. That said, it is strongly
|
|
recommended to call
|
|
<link linkend="igraph_setup"><function>igraph_setup()</function></link>
|
|
before using any other function, as future &igraph; versions may add critical
|
|
initialization steps.
|
|
</para>
|
|
|
|
<!-- doxrox-include igraph_setup -->
|
|
</section>
|
|
|
|
<section id="basic-interface"><title>The basic interface</title>
|
|
<!-- doxrox-include about_basic_interface -->
|
|
|
|
<section id="graph-constructors-and-destructors"><title>Graph constructors and destructors</title>
|
|
<!-- doxrox-include igraph_empty -->
|
|
<!-- doxrox-include igraph_empty_attrs -->
|
|
<!-- doxrox-include igraph_copy -->
|
|
<!-- doxrox-include igraph_destroy -->
|
|
</section>
|
|
|
|
<section id="basic-query-operations"><title>Basic query operations</title>
|
|
<!-- doxrox-include igraph_vcount -->
|
|
<!-- doxrox-include igraph_ecount -->
|
|
<!-- doxrox-include igraph_is_directed -->
|
|
<!-- doxrox-include igraph_edge -->
|
|
<!-- doxrox-include igraph_edges -->
|
|
<!-- doxrox-include IGRAPH_FROM -->
|
|
<!-- doxrox-include IGRAPH_TO -->
|
|
<!-- doxrox-include IGRAPH_OTHER -->
|
|
<!-- doxrox-include igraph_get_eid -->
|
|
<!-- doxrox-include igraph_get_eids -->
|
|
<!-- doxrox-include igraph_get_all_eids_between -->
|
|
<!-- doxrox-include igraph_neighbors -->
|
|
<!-- doxrox-include igraph_incident -->
|
|
<!-- doxrox-include igraph_degree -->
|
|
<!-- doxrox-include igraph_degree_1 -->
|
|
</section>
|
|
|
|
<section id="adding-and-deleting-vertices-and-edges"><title>Adding and deleting vertices and edges</title>
|
|
<!-- doxrox-include igraph_add_edge -->
|
|
<!-- doxrox-include igraph_add_edges -->
|
|
<!-- doxrox-include igraph_add_vertices -->
|
|
<!-- doxrox-include igraph_delete_edges -->
|
|
<!-- doxrox-include igraph_delete_vertices -->
|
|
<!-- doxrox-include igraph_delete_vertices_map -->
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="misc-helper-functions"><title>Miscellaneous macros and helper functions</title>
|
|
<!-- doxrox-include IGRAPH_VCOUNT_MAX -->
|
|
<!-- doxrox-include IGRAPH_ECOUNT_MAX -->
|
|
<!-- doxrox-include IGRAPH_UNLIMITED -->
|
|
<!-- doxrox-include igraph_expand_path_to_pairs -->
|
|
<!-- doxrox-include igraph_invalidate_cache -->
|
|
<!-- doxrox-include igraph_is_same_graph -->
|
|
</section>
|
|
|
|
</chapter>
|