abdelrahman/agent_compositor_test
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
agent_compositor_test/references/igraph-1.0.1/doc/html/igraph-Visitors.html
T
Abdelrahman Said a11edf0c53 Add graph references
2026-06-28 13:49:01 +01:00

1058 lines
46 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 16. Graph visitors</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="igraph Reference Manual">
<link rel="up" href="index.html" title="igraph Reference Manual">
<link rel="prev" href="igraph-Operators.html" title="Chapter 15. Graph operators">
<link rel="next" href="igraph-Structural.html" title="Chapter 17. Structural properties of graphs">
<script type="text/javascript" src="toggle.js"></script><link rel="stylesheet" href="style.css" type="text/css">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" type="text/css">
<link rel="chapter" href="igraph-Introduction.html" title="Chapter 1. Introduction">
<link rel="chapter" href="igraph-Installation.html" title="Chapter 2. Installation">
<link rel="chapter" href="igraph-Tutorial.html" title="Chapter 3. Tutorial">
<link rel="chapter" href="igraph-Basic.html" title="Chapter 4. Basic data types and interface">
<link rel="chapter" href="igraph-Error.html" title="Chapter 5. Error handling">
<link rel="chapter" href="igraph-Memory.html" title="Chapter 6. Memory (de)allocation">
<link rel="chapter" href="igraph-Data-structures.html" title="Chapter 7. Data structure library: vector, matrix, other data types">
<link rel="chapter" href="igraph-Random.html" title="Chapter 8. Random numbers">
<link rel="chapter" href="igraph-Iterators.html" title="Chapter 9. Vertex and edge selectors and sequences, iterators">
<link rel="chapter" href="igraph-Attributes.html" title="Chapter 10. Graph, vertex and edge attributes">
<link rel="chapter" href="igraph-Generators.html" title="Chapter 11. Deterministic graph generators">
<link rel="chapter" href="igraph-Games.html" title='Chapter 12. Stochastic graph generators ("games")'>
<link rel="chapter" href="igraph-Bipartite.html" title="Chapter 13. Bipartite, i.e. two-mode graphs">
<link rel="chapter" href="igraph-Spatial.html" title="Chapter 14. Spatial graphs">
<link rel="chapter" href="igraph-Operators.html" title="Chapter 15. Graph operators">
<link rel="chapter" href="igraph-Visitors.html" title="Chapter 16. Graph visitors">
<link rel="chapter" href="igraph-Structural.html" title="Chapter 17. Structural properties of graphs">
<link rel="chapter" href="igraph-Cycles.html" title="Chapter 18. Graph cycles">
<link rel="chapter" href="igraph-Cliques.html" title="Chapter 19. Cliques and independent vertex sets">
<link rel="chapter" href="igraph-Motifs.html" title="Chapter 20. Graph motifs, dyad census and triad census">
<link rel="chapter" href="igraph-Isomorphism.html" title="Chapter 21. Graph isomorphism">
<link rel="chapter" href="igraph-Coloring.html" title="Chapter 22. Graph coloring">
<link rel="chapter" href="igraph-Flows.html" title="Chapter 23. Maximum flows, minimum cuts and related measures">
<link rel="chapter" href="igraph-Separators.html" title="Chapter 24. Vertex separators">
<link rel="chapter" href="igraph-Community.html" title="Chapter 25. Detecting community structure">
<link rel="chapter" href="igraph-Graphlets.html" title="Chapter 26. Graphlets">
<link rel="chapter" href="igraph-HRG.html" title="Chapter 27. Hierarchical random graphs">
<link rel="chapter" href="igraph-Embedding.html" title="Chapter 28. Embedding of graphs">
<link rel="chapter" href="igraph-Layout.html" title="Chapter 29. Generating layouts for graph drawing">
<link rel="chapter" href="igraph-Processes.html" title="Chapter 30. Processes on graphs">
<link rel="chapter" href="igraph-Foreign.html" title="Chapter 31. Reading and writing graphs from and to files">
<link rel="chapter" href="igraph-Linalg.html" title="Chapter 32. Using BLAS, LAPACK and ARPACK for igraph matrices and graphs">
<link rel="chapter" href="igraph-Nongraph.html" title="Chapter 33. Non-graph related functions">
<link rel="chapter" href="igraph-Advanced.html" title="Chapter 34. Advanced igraph programming">
<link rel="chapter" href="igraph-Glossary.html" title="Chapter 35. Glossary">
<link rel="chapter" href="igraph-Licenses.html" title="Chapter 36. Licenses for igraph and this manual">
<link rel="index" href="ix01.html" title="Index">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navigation-header mb-4" width="100%" summary="Navigation header"><div class="btn-group">
<a accesskey="p" class="btn btn-light" href="igraph-Operators.html"><i class="fa fa-chevron-left"></i>
Previous
</a><a accesskey="h" class="btn btn-light" href="index.html"><i class="fa fa-home"></i>
Home
</a><a accesskey="n" class="btn btn-light" href="igraph-Structural.html"><i class="fa fa-chevron-right"></i>
Next
</a>
</div></div>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="igraph-Visitors"></a>Chapter 16. Graph visitors</h1></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="igraph-Visitors.html#breadth-first-search">1. Breadth-first search</a></span></dt>
<dt><span class="section"><a href="igraph-Visitors.html#depth-first-search">2. Depth-first search</a></span></dt>
<dt><span class="section"><a href="igraph-Visitors.html#random-walks">3. Random walks</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="breadth-first-search"></a>1. Breadth-first search</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="igraph-Visitors.html#igraph_bfs">1.1. <code class="function">igraph_bfs</code> — Breadth-first search.</a></span></dt>
<dt><span class="section"><a href="igraph-Visitors.html#igraph_bfs_simple">1.2. <code class="function">igraph_bfs_simple</code> — Breadth-first search, single-source version</a></span></dt>
<dt><span class="section"><a href="igraph-Visitors.html#igraph_bfshandler_t">1.3. <code class="function">igraph_bfshandler_t</code> — Callback type for BFS function.</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_bfs"></a>1.1. <code class="function">igraph_bfs</code> — Breadth-first search.</h3></div></div></div>
<a class="indexterm" name="id-1.17.2.2.2"></a><p>
</p>
<div class="informalexample"><pre class="programlisting">
igraph_error_t igraph_bfs(const igraph_t *graph,
igraph_int_t root, const igraph_vector_int_t *roots,
igraph_neimode_t mode, igraph_bool_t unreachable,
const igraph_vector_int_t *restricted,
igraph_vector_int_t *order, igraph_vector_int_t *rank,
igraph_vector_int_t *parents,
igraph_vector_int_t *pred, igraph_vector_int_t *succ,
igraph_vector_int_t *dist, igraph_bfshandler_t *callback,
void *extra);
</pre></div>
<p>
</p>
<p>
A simple breadth-first search, with a lot of different results and
the possibility to call a callback whenever a vertex is visited.
It is allowed to supply null pointers as the output arguments the
user is not interested in, in this case they will be ignored.
</p>
<p>
If not all vertices can be reached from the supplied root vertex,
then additional root vertices will be used, in the order of their
vertex IDs.
</p>
<p>
Consider using <a class="link" href="igraph-Visitors.html#igraph_bfs_simple" title="1.2. igraph_bfs_simple — Breadth-first search, single-source version"><code class="function">igraph_bfs_simple</code></a> instead if you set most of the output
arguments provided by this function to a null pointer.
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The input graph.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>root</code></em>:</span></p></td>
<td><p>
The id of the root vertex. It is ignored if the <code class="constant">roots</code> argument is not a null pointer.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>roots</code></em>:</span></p></td>
<td><p>
Pointer to an initialized vector, or a null
pointer. If not a null pointer, then it is a vector
containing root vertices to start the BFS from. The vertices
are considered in the order they appear. If a root vertex
was already found while searching from another one, then no
search is conducted from it.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mode</code></em>:</span></p></td>
<td><p>
For directed graphs, it defines which edges to follow.
<code class="constant">IGRAPH_OUT</code> means following the direction of the edges,
<code class="constant">IGRAPH_IN</code> means the opposite, and
<code class="constant">IGRAPH_ALL</code> ignores the direction of the edges.
This parameter is ignored for undirected graphs.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>unreachable</code></em>:</span></p></td>
<td><p>
Boolean, whether the search should visit
the vertices that are unreachable from the given root
node(s). If true, then additional searches are performed
until all vertices are visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>restricted</code></em>:</span></p></td>
<td><p>
If not a null pointer, then it must be a pointer
to a vector containing vertex IDs. The BFS is carried out
only on these vertices.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>order</code></em>:</span></p></td>
<td><p>
If not null pointer, then the vertex IDs of the graph are
stored here, in the same order as they were visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>rank</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the rank of each vertex is
stored here.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parents</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the id of the parent of
each vertex is stored here. When a vertex was not visited
during the traversal, -2 will be stored as the ID of its parent.
When a vertex was visited during the traversal and it was one of
the roots of the search trees, -1 will be stored as the ID of
its parent.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pred</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the id of vertex that was
visited before the current one is stored here. If there is
no such vertex (the current vertex is the root of a search
tree), then -1 is stored as the predecessor of the vertex.
If the vertex was not visited at all, then -2 is stored for
the predecessor of the vertex.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>succ</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the id of the vertex that
was visited after the current one is stored here. If there
is no such vertex (the current one is the last in a search
tree), then -1 is stored as the successor of the vertex.
If the vertex was not visited at all, then -2 is stored for
the successor of the vertex.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dist</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the distance from the root of
the current search tree is stored here for each vertex. If a
vertex was not reached during the traversal, its distance will
be -1 in this vector.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>callback</code></em>:</span></p></td>
<td><p>
If not null, then it should be a pointer to a
function of type <a class="link" href="igraph-Visitors.html#igraph_bfshandler_t" title="1.3. igraph_bfshandler_t — Callback type for BFS function."><code class="function">igraph_bfshandler_t</code></a>. This function
will be called, whenever a new vertex is visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>extra</code></em>:</span></p></td>
<td><p>
Extra argument to pass to the callback function.
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
Error code.
</p></td>
</tr></tbody>
</table></div>
<p>
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
</p>
<div class="hideshow" onClick="toggle(this, event)">
<div class="example">
<a name="id-1.17.2.2.10.1"></a><p class="title"><b>Example 16.1.  File <code class="code">examples/simple/igraph_bfs.c</code></b></p>
<div class="example-contents">
<pre class="programlisting"><span class="strong"><strong>#include</strong></span> &lt;igraph.h&gt;
int <span class="strong"><strong>main</strong></span>(void) {
igraph_t graph, ring;
igraph_vector_int_t order, rank, father, pred, succ, dist;
<span class="emphasis"><em>/* Initialize the library. */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_setup" title="4.1. igraph_setup — Initializes the igraph library.">igraph_setup</a></strong></span>();
<span class="emphasis"><em>/* Create a disjoint union of two rings */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Generators.html#igraph_ring" title="4.7. igraph_ring — Creates a cycle graph or a path graph.">igraph_ring</a></strong></span>(&amp;ring, 10, <span class="emphasis"><em>/*directed=*/</em></span> 0, <span class="emphasis"><em>/*mutual=*/</em></span> 0, <span class="emphasis"><em>/*circular=*/</em></span> 1);
<span class="strong"><strong><a class="link" href="igraph-Operators.html#igraph_disjoint_union" title="1.1. igraph_disjoint_union — Creates the union of two disjoint graphs.">igraph_disjoint_union</a></strong></span>(&amp;graph, &amp;ring, &amp;ring);
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&amp;ring);
<span class="emphasis"><em>/* Initialize the vectors where the result will be stored. Any of these</em></span>
<span class="emphasis"><em> * can be omitted and replaced with a null pointer when calling</em></span>
<span class="emphasis"><em> * igraph_bfs() */</em></span>
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;order, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;rank, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;father, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;pred, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;succ, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;dist, 0);
<span class="emphasis"><em>/* Now call the BFS function */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search.">igraph_bfs</a></strong></span>(&amp;graph, <span class="emphasis"><em>/*root=*/</em></span>0, <span class="emphasis"><em>/*roots=*/</em></span> NULL, <span class="emphasis"><em>/*neimode=*/</em></span> IGRAPH_OUT,
<span class="emphasis"><em>/*unreachable=*/</em></span> 1, <span class="emphasis"><em>/*restricted=*/</em></span> NULL,
&amp;order, &amp;rank, &amp;father, &amp;pred, &amp;succ, &amp;dist,
<span class="emphasis"><em>/*callback=*/</em></span> NULL, <span class="emphasis"><em>/*extra=*/</em></span> NULL);
<span class="emphasis"><em>/* Print the results */</em></span>
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;order);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;rank);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;father);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;pred);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;succ);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;dist);
<span class="emphasis"><em>/* Cleam up after ourselves */</em></span>
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;order);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;rank);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;father);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;pred);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;succ);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;dist);
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&amp;graph);
<span class="strong"><strong>return</strong></span> 0;
}
</pre>
<p></p>
</div>
</div>
<br class="example-break">
</div>
<div class="hideshow" onClick="toggle(this, event)">
<div class="example">
<a name="id-1.17.2.2.10.2"></a><p class="title"><b>Example 16.2.  File <code class="code">examples/simple/igraph_bfs_callback.c</code></b></p>
<div class="example-contents">
<pre class="programlisting"><span class="strong"><strong>#include</strong></span> &lt;igraph.h&gt;
<a class="link" href="igraph-Error.html#igraph_error_t" title="3.1. igraph_error_t — Return type for functions returning an error code.">igraph_error_t</a> <span class="strong"><strong>bfs_callback</strong></span>(<span class="strong"><strong>const</strong></span> igraph_t *graph,
igraph_int_t vid,
igraph_int_t pred,
igraph_int_t succ,
igraph_int_t rank,
igraph_int_t dist,
void *extra) {
<span class="strong"><strong>IGRAPH_UNUSED</strong></span>(graph);
<span class="strong"><strong>IGRAPH_UNUSED</strong></span>(pred);
<span class="strong"><strong>IGRAPH_UNUSED</strong></span>(succ);
<span class="strong"><strong>IGRAPH_UNUSED</strong></span>(rank);
<span class="strong"><strong>IGRAPH_UNUSED</strong></span>(dist);
<span class="strong"><strong>printf</strong></span>(" %" IGRAPH_PRId "", vid);
<span class="strong"><strong>return</strong></span> IGRAPH_SUCCESS;
}
int <span class="strong"><strong>main</strong></span>(void) {
igraph_t graph, ring;
<span class="emphasis"><em>/* Initialize the library. */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_setup" title="4.1. igraph_setup — Initializes the igraph library.">igraph_setup</a></strong></span>();
<span class="emphasis"><em>/* Create a disjoint union of two rings */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Generators.html#igraph_ring" title="4.7. igraph_ring — Creates a cycle graph or a path graph.">igraph_ring</a></strong></span>(&amp;ring, 10, <span class="emphasis"><em>/*directed=*/</em></span> 0, <span class="emphasis"><em>/*mutual=*/</em></span> 0, <span class="emphasis"><em>/*circular=*/</em></span> 1);
<span class="strong"><strong><a class="link" href="igraph-Operators.html#igraph_disjoint_union" title="1.1. igraph_disjoint_union — Creates the union of two disjoint graphs.">igraph_disjoint_union</a></strong></span>(&amp;graph, &amp;ring, &amp;ring);
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&amp;ring);
<span class="emphasis"><em>/* Now call the BFS function */</em></span>
<span class="strong"><strong>printf</strong></span>("(");
<span class="strong"><strong><a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search.">igraph_bfs</a></strong></span>(&amp;graph, <span class="emphasis"><em>/*root=*/</em></span>0, <span class="emphasis"><em>/*roots=*/</em></span> 0, <span class="emphasis"><em>/*neimode=*/</em></span> IGRAPH_OUT,
<span class="emphasis"><em>/*unreachable=*/</em></span> 1, <span class="emphasis"><em>/*restricted=*/</em></span> 0,
<span class="emphasis"><em>/*order=*/</em></span> 0, <span class="emphasis"><em>/*rank=*/</em></span> 0, <span class="emphasis"><em>/*father=*/</em></span> 0, <span class="emphasis"><em>/*pred=*/</em></span> 0,
<span class="emphasis"><em>/*succ=*/</em></span> 0, <span class="emphasis"><em>/*dist=*/</em></span> 0,
<span class="emphasis"><em>/*callback=*/</em></span> bfs_callback, <span class="emphasis"><em>/*extra=*/</em></span> 0);
<span class="strong"><strong>printf</strong></span>(" )\n");
<span class="emphasis"><em>/* Cleam up after ourselves */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&amp;graph);
<span class="strong"><strong>return</strong></span> 0;
}
</pre>
<p></p>
</div>
</div>
<br class="example-break">
</div>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_bfs_simple"></a>1.2. <code class="function">igraph_bfs_simple</code> — Breadth-first search, single-source version</h3></div></div></div>
<a class="indexterm" name="id-1.17.2.3.2"></a><p>
</p>
<div class="informalexample"><pre class="programlisting">
igraph_error_t igraph_bfs_simple(
const igraph_t *graph, igraph_int_t root, igraph_neimode_t mode,
igraph_vector_int_t *order, igraph_vector_int_t *layers,
igraph_vector_int_t *parents
);
</pre></div>
<p>
</p>
<p>
An alternative breadth-first search implementation to cater for the
simpler use-cases when only a single breadth-first search has to be conducted
from a source node and most of the output arguments from <a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search."><code class="function">igraph_bfs</code></a>
are not needed. It is allowed to supply null pointers as
the output arguments the user is not interested in, in this case they will
be ignored.
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The input graph.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>root</code></em>:</span></p></td>
<td><p>
The id of the root vertex.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mode</code></em>:</span></p></td>
<td><p>
For directed graphs, it defines which edges to follow.
<code class="constant">IGRAPH_OUT</code> means following the direction of the edges,
<code class="constant">IGRAPH_IN</code> means the opposite, and
<code class="constant">IGRAPH_ALL</code> ignores the direction of the edges.
This parameter is ignored for undirected graphs.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>order</code></em>:</span></p></td>
<td><p>
If not a null pointer, then an initialized vector must be passed
here. The IDs of the vertices visited during the traversal will be
stored here, in the same order as they were visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>layers</code></em>:</span></p></td>
<td><p>
If not a null pointer, then an initialized vector must be
passed here. The i-th element of the vector will contain the index
into <code class="constant">order</code> where the vertices that are at distance i from the root
are stored. In other words, if you are interested in the vertices that
are at distance i from the root, you need to look in the <code class="constant">order</code>
vector from <code class="constant">layers</code>[i] to <code class="constant">layers</code>[i+1].
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parents</code></em>:</span></p></td>
<td><p>
If not a null pointer, then an initialized vector must be
passed here. The vector will be resized so its length is equal to the
number of nodes, and it will contain the index of the parent node for
each <span class="emphasis"><em>visited</em></span> node. The values in the vector are set to -2 for
vertices that were <span class="emphasis"><em>not</em></span> visited, and -1 for the root vertex.
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
Error code.
</p></td>
</tr></tbody>
</table></div>
<p>
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
</p>
<div class="hideshow" onClick="toggle(this, event)">
<div class="example">
<a name="id-1.17.2.3.8.1"></a><p class="title"><b>Example 16.3.  File <code class="code">examples/simple/igraph_bfs_simple.c</code></b></p>
<div class="example-contents">
<pre class="programlisting"><span class="strong"><strong>#include</strong></span> &lt;igraph.h&gt;
int <span class="strong"><strong>main</strong></span>(void) {
igraph_t g;
igraph_vector_int_t vids, layers, parents;
<span class="emphasis"><em>/* Initialize the library. */</em></span>
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_setup" title="4.1. igraph_setup — Initializes the igraph library.">igraph_setup</a></strong></span>();
<span class="strong"><strong><a class="link" href="igraph-Generators.html#igraph_ring" title="4.7. igraph_ring — Creates a cycle graph or a path graph.">igraph_ring</a></strong></span>(&amp;g, 10, IGRAPH_UNDIRECTED, 0, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;vids, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;layers, 0);
<span class="strong"><strong>igraph_vector_int_init</strong></span>(&amp;parents, 0);
<span class="strong"><strong><a class="link" href="igraph-Visitors.html#igraph_bfs_simple" title="1.2. igraph_bfs_simple — Breadth-first search, single-source version">igraph_bfs_simple</a></strong></span>(&amp;g, 0, IGRAPH_ALL, &amp;vids, &amp;layers, &amp;parents);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;vids);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;layers);
<span class="strong"><strong>igraph_vector_int_print</strong></span>(&amp;parents);
<span class="strong"><strong><a class="link" href="igraph-Basic.html#igraph_destroy" title="5.1.4. igraph_destroy — Frees the memory allocated for a graph object.">igraph_destroy</a></strong></span>(&amp;g);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;vids);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;layers);
<span class="strong"><strong>igraph_vector_int_destroy</strong></span>(&amp;parents);
<span class="strong"><strong>return</strong></span> 0;
}
</pre>
<p></p>
</div>
</div>
<br class="example-break">
</div>
<p>
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_bfshandler_t"></a>1.3. <code class="function">igraph_bfshandler_t</code> — Callback type for BFS function.</h3></div></div></div>
<a class="indexterm" name="id-1.17.2.4.2"></a><pre class="programlisting">
typedef igraph_error_t igraph_bfshandler_t(const igraph_t *graph,
igraph_int_t vid,
igraph_int_t pred,
igraph_int_t succ,
igraph_int_t rank,
igraph_int_t dist,
void *extra);
</pre>
<p>
<a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search."><code class="function">igraph_bfs()</code></a> is able to call a callback function, whenever a
new vertex is found, while doing the breadth-first search. This
callback function must be of type <code class="constant">igraph_bfshandler_t</code>. It has
the following arguments:
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The graph that the algorithm is working on. Of course
this must not be modified.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>vid</code></em>:</span></p></td>
<td><p>
The id of the vertex just found by the breadth-first
search.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>pred</code></em>:</span></p></td>
<td><p>
The id of the previous vertex visited. It is -1 if
there is no previous vertex, because the current vertex is the root
is a search tree.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>succ</code></em>:</span></p></td>
<td><p>
The id of the next vertex that will be visited. It is
-1 if there is no next vertex, because the current vertex is the
last one in a search tree.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>rank</code></em>:</span></p></td>
<td><p>
The rank of the current vertex, it starts with zero.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dist</code></em>:</span></p></td>
<td><p>
The distance (number of hops) of the current vertex
from the root of the current search tree.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>extra</code></em>:</span></p></td>
<td><p>
The extra argument that was passed to <a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search."><code class="function">igraph_bfs()</code></a>.
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
<code class="constant">IGRAPH_SUCCESS</code> if the BFS should continue, <code class="constant">IGRAPH_STOP</code>
if the BFS should stop and return to the caller normally. Any other
value is treated as an igraph error code, terminating the search and
returning to the caller with the same error code. If a BFS is
is terminated prematurely, then all elements of the result vectors
that were not yet calculated at the point of the termination
contain negative values.
</p></td>
</tr></tbody>
</table></div>
<p>
</p>
<p><b>See also: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
<a class="link" href="igraph-Visitors.html#igraph_bfs" title="1.1. igraph_bfs — Breadth-first search."><code class="function">igraph_bfs()</code></a>
</p></td>
</tr></tbody>
</table></div>
<p>
</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="depth-first-search"></a>2. Depth-first search</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="igraph-Visitors.html#igraph_dfs">2.1. <code class="function">igraph_dfs</code> — Depth-first search.</a></span></dt>
<dt><span class="section"><a href="igraph-Visitors.html#igraph_dfshandler_t">2.2. <code class="function">igraph_dfshandler_t</code> — Callback type for the DFS function.</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_dfs"></a>2.1. <code class="function">igraph_dfs</code> — Depth-first search.</h3></div></div></div>
<a class="indexterm" name="id-1.17.3.2.2"></a><p>
</p>
<div class="informalexample"><pre class="programlisting">
igraph_error_t igraph_dfs(const igraph_t *graph, igraph_int_t root,
igraph_neimode_t mode, igraph_bool_t unreachable,
igraph_vector_int_t *order,
igraph_vector_int_t *order_out, igraph_vector_int_t *parents,
igraph_vector_int_t *dist, igraph_dfshandler_t *in_callback,
igraph_dfshandler_t *out_callback,
void *extra);
</pre></div>
<p>
</p>
<p>
A simple depth-first search, with
the possibility to call a callback whenever a vertex is discovered
and/or whenever a subtree is finished.
It is allowed to supply null pointers as the output arguments the
user is not interested in, in this case they will be ignored.
</p>
<p>
If not all vertices can be reached from the supplied root vertex,
then additional root vertices will be used, in the order of their
vertex IDs.
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The input graph.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>root</code></em>:</span></p></td>
<td><p>
The id of the root vertex.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mode</code></em>:</span></p></td>
<td><p>
For directed graphs, it defines which edges to follow.
<code class="constant">IGRAPH_OUT</code> means following the direction of the edges,
<code class="constant">IGRAPH_IN</code> means the opposite, and
<code class="constant">IGRAPH_ALL</code> ignores the direction of the edges.
This parameter is ignored for undirected graphs.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>unreachable</code></em>:</span></p></td>
<td><p>
Boolean, whether the search should visit
the vertices that are unreachable from the given root
node(s). If true, then additional searches are performed
until all vertices are visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>order</code></em>:</span></p></td>
<td><p>
If not null pointer, then the vertex IDs of the graph are
stored here, in the same order as they were discovered. The tail of
the vector will be padded with -1 to ensure that the length of the
vector is the same as the number of vertices, even if some vertices
were not visited during the traversal.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>order_out</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the vertex IDs of the
graphs are stored here, in the order of the completion of
their subtree. The tail of the vector will be padded with -1 to ensure
that the length of the vector is the same as the number of vertices,
even if some vertices were not visited during the traversal.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parents</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the id of the parent of
each vertex is stored here. -1 will be stored for the root of the
search tree; -2 will be stored for vertices that were not visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dist</code></em>:</span></p></td>
<td><p>
If not a null pointer, then the distance from the root of
the current search tree is stored here. -1 will be stored for vertices
that were not visited.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>in_callback</code></em>:</span></p></td>
<td><p>
If not null, then it should be a pointer to a
function of type <a class="link" href="igraph-Visitors.html#igraph_dfshandler_t" title="2.2. igraph_dfshandler_t — Callback type for the DFS function."><code class="function">igraph_dfshandler_t</code></a>. This function
will be called, whenever a new vertex is discovered.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>out_callback</code></em>:</span></p></td>
<td><p>
If not null, then it should be a pointer to a
function of type <a class="link" href="igraph-Visitors.html#igraph_dfshandler_t" title="2.2. igraph_dfshandler_t — Callback type for the DFS function."><code class="function">igraph_dfshandler_t</code></a>. This function
will be called, whenever the subtree of a vertex is completed.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>extra</code></em>:</span></p></td>
<td><p>
Extra argument to pass to the callback function(s).
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
Error code.
</p></td>
</tr></tbody>
</table></div>
<p>
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_dfshandler_t"></a>2.2. <code class="function">igraph_dfshandler_t</code> — Callback type for the DFS function.</h3></div></div></div>
<a class="indexterm" name="id-1.17.3.3.2"></a><p>
</p>
<div class="informalexample"><pre class="programlisting">
typedef igraph_error_t igraph_dfshandler_t(const igraph_t *graph,
igraph_int_t vid,
igraph_int_t dist,
void *extra);
</pre></div>
<p>
</p>
<p>
<a class="link" href="igraph-Visitors.html#igraph_dfs" title="2.1. igraph_dfs — Depth-first search."><code class="function">igraph_dfs()</code></a> is able to call a callback function, whenever a
new vertex is discovered, and/or whenever a subtree is
completed. These callbacks must be of type <code class="constant">igraph_dfshandler_t</code>. They have the following arguments:
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The graph that the algorithm is working on. Of course
this must not be modified.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>vid</code></em>:</span></p></td>
<td><p>
The id of the vertex just found by the depth-first
search.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>dist</code></em>:</span></p></td>
<td><p>
The distance (number of hops) of the current vertex
from the root of the current search tree.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>extra</code></em>:</span></p></td>
<td><p>
The extra argument that was passed to <a class="link" href="igraph-Visitors.html#igraph_dfs" title="2.1. igraph_dfs — Depth-first search."><code class="function">igraph_dfs()</code></a>.
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
<code class="constant">IGRAPH_SUCCESS</code> if the DFS should continue, <code class="constant">IGRAPH_STOP</code>
if the DFS should stop and return to the caller normally. Any other
value is treated as an igraph error code, terminating the search and
returning to the caller with the same error code. If a DFS is
is terminated prematurely, then all elements of the result vectors
that were not yet calculated at the point of the termination
contain negative values.
</p></td>
</tr></tbody>
</table></div>
<p>
</p>
<p><b>See also: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
<a class="link" href="igraph-Visitors.html#igraph_dfs" title="2.1. igraph_dfs — Depth-first search."><code class="function">igraph_dfs()</code></a>
</p></td>
</tr></tbody>
</table></div>
<p>
</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="random-walks"></a>3. Random walks</h2></div></div></div>
<div class="toc"><dl class="toc"><dt><span class="section"><a href="igraph-Visitors.html#igraph_random_walk">3.1. <code class="function">igraph_random_walk</code> — Performs a random walk on a graph.</a></span></dt></dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="igraph_random_walk"></a>3.1. <code class="function">igraph_random_walk</code> — Performs a random walk on a graph.</h3></div></div></div>
<a class="indexterm" name="id-1.17.4.2.2"></a><p>
</p>
<div class="informalexample"><pre class="programlisting">
igraph_error_t igraph_random_walk(const igraph_t *graph,
const igraph_vector_t *weights,
igraph_vector_int_t *vertices,
igraph_vector_int_t *edges,
igraph_int_t start,
igraph_neimode_t mode,
igraph_int_t steps,
igraph_random_walk_stuck_t stuck);
</pre></div>
<p>
</p>
<p>
Performs a random walk with a given length on a graph, from the given
start vertex. Edge directions are (potentially) considered, depending on
the <em class="parameter"><code>mode</code></em> argument.
</p>
<p><b>Arguments: </b>
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>graph</code></em>:</span></p></td>
<td><p>
The input graph, it can be directed or undirected.
Multiple edges are respected, so are loop edges.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>weights</code></em>:</span></p></td>
<td><p>
A vector of non-negative edge weights. It is assumed
that at least one strictly positive weight is found among the
outgoing edges of each vertex. Additionally, no edge weight may
be NaN. If either case does not hold, an error is returned. If it
is <code class="constant">NULL</code>, all edges are considered to have equal weight.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>vertices</code></em>:</span></p></td>
<td><p>
An allocated vector, the result is stored here as
a list of vertex IDs. It will be resized as needed.
It includes the vertex IDs of starting and ending vertices.
Length of the vertices vector: <em class="parameter"><code>steps</code></em> + 1
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>edges</code></em>:</span></p></td>
<td><p>
An initialized vector, the indices of traversed
edges are stored here. It will be resized as needed.
Length of the edges vector: <em class="parameter"><code>steps</code></em>
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>start</code></em>:</span></p></td>
<td><p>
The start vertex for the walk.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>mode</code></em>:</span></p></td>
<td><p>
How to walk along the edges in directed graphs.
<code class="constant">IGRAPH_OUT</code> means following edge directions, <code class="constant">IGRAPH_IN</code> means
going opposite the edge directions, <code class="constant">IGRAPH_ALL</code> means ignoring
edge directions. This argument is ignored for undirected graphs.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>steps</code></em>:</span></p></td>
<td><p>
The number of steps to take. If the random walk gets
stuck, then the <em class="parameter"><code>stuck</code></em> argument specifies what happens.
<em class="parameter"><code>steps</code></em> is the number of edges to traverse during the walk.
</p></td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>stuck</code></em>:</span></p></td>
<td><p>
What to do if the random walk gets stuck.
<code class="constant">IGRAPH_RANDOM_WALK_STUCK_RETURN</code> means that the function returns
with a shorter walk; <code class="constant">IGRAPH_RANDOM_WALK_STUCK_ERROR</code> means
that an <code class="constant">IGRAPH_ERWSTUCK</code> error is reported.
In both cases, <em class="parameter"><code>vertices</code></em> and <em class="parameter"><code>edges</code></em> are truncated to contain
the actual interrupted walk.
</p></td>
</tr>
</tbody>
</table></div>
<p>
</p>
<p><b>Returns: </b></p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code></code></em></span></p></td>
<td><p>
Error code: <code class="constant">IGRAPH_ERWSTUCK</code> if the walk got stuck.
</p></td>
</tr></tbody>
</table></div>
<p>
Time complexity:
O(l + d) for unweighted graphs and
O(l * log(k) + d) for weighted graphs,
where <code class="constant">l</code> is the length of the walk, <code class="constant">d</code> is the total degree of the visited nodes
and <code class="constant">k</code> is the average degree of vertices of the given graph.
</p>
</div>
</div>
</div>
<table class="navigation-footer" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle">
<td align="left"><a accesskey="p" href="igraph-Operators.html"><b>← Chapter 15. Graph operators</b></a></td>
<td align="right"><a accesskey="n" href="igraph-Structural.html"><b>Chapter 17. Structural properties of graphs →</b></a></td>
</tr></table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink