Add graph references
This commit is contained in:
Abdelrahman Said
@@ -0,0 +1,241 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user