This is igraph_reference_manual.info, produced by makeinfo version 4.8
from igraph.texi.
INFO-DIR-SECTION Development
START-INFO-DIR-ENTRY
* Igraph Reference Manual: (igraph.info). A library for graphs
END-INFO-DIR-ENTRY
File: igraph_reference_manual.info, Node: Top, Next: Introduction, Up: (dir)
igraph Reference Manual
***********************
* Menu:
* Introduction::
* Installation::
* Tutorial::
* About igraph graphs, the basic interface: About igraph graphs; the basic interface.
* Error Handling::
* Memory (de)allocation: Memory [de]allocation.
* Data structure library; vector, matrix, other data types: Data structure library; vector; matrix; other data types.
* Random numbers::
* Graph Generators::
* Games on Graphs::
* Vertex and Edge Selectors and Sequences, Iterators: Vertex and Edge Selectors and Sequences; Iterators.
* Graph, Vertex and Edge Attributes: Graph; Vertex and Edge Attributes.
* Structural Properties of Graphs::
* Graph visitors::
* Cliques and Independent Vertex Sets::
* Graph Isomorphism::
* Graph Motifs, Dyad Census and Triad Census: Graph Motifs; Dyad Census and Triad Census.
* Generating Layouts for Graph Drawing::
* Reading and Writing Graphs from and to Files::
* Maximum Flows, Minimum Cuts and related measures: Maximum Flows; Minimum Cuts and related measures.
* Vertex separators::
* Detecting Community Structure::
* Graphlets::
* Hierarchical random graphs::
* Spectral Coarse Graining::
* Graph Operators::
* Using BLAS, LAPACK and ARPACK for igraph matrices and graphs: Using BLAS; LAPACK and ARPACK for igraph matrices and graphs.
* Bipartite, i.e. two-mode graphs: Bipartite; i_e_ two-mode graphs.
* Advanced igraph programming::
* Not Graph Related Functions : Not Graph Related Functions.
* Licenses for igraph and this manual::
* Index: Concept index.
--- The Detailed Node Listing ---
Introduction
* igraph is free software::
* Citing igraph::
Tutorial
* Lesson 1. Compiling programs using igraph.: Lesson 1_ Compiling programs using igraph_.
* Lesson 2. Creating your first graphs.: Lesson 2_ Creating your first graphs_.
* Lesson 3. Calculating various properties of graphs.: Lesson 3_ Calculating various properties of graphs_.
About igraph graphs, the basic interface
* The igraph data model::
* The basic interface::
Error Handling
* Error handling basics::
* Error handlers::
* Error codes::
* Warning messages::
* Advanced topics::
Memory (de)allocation
* igraph_free --- Deallocate memory that was allocated by igraph functions::
Data structure library: vector, matrix, other data types
* About template types::
* Vectors::
* Matrices::
* Sparse matrices::
* Sparse matrices, another kind: Sparse matrices; another kind.
* Stacks::
* Double-ended queues::
* Maximum and minimum heaps::
* String vectors::
* Adjacency lists::
Random numbers
* About random numbers in igraph, use cases: About random numbers in igraph; use cases.
* The default random number generator::
* Creating random number generators::
* Generating random numbers::
* Supported random number generators::
* Use cases::
Graph Generators
* Deterministic Graph Generators::
* Games; Randomized Graph Generators::
Games on Graphs
* Microscopic Update Rules::
Vertex and Edge Selectors and Sequences, Iterators
* About selectors, iterators: About selectors; iterators.
* Vertex selector constructors::
* Generic vertex selector operations::
* Immediate vertex selectors::
* Vertex iterators::
* Edge selector constructors::
* Immediate edge selectors::
* Generic edge selector operations::
* Edge iterators::
Graph, Vertex and Edge Attributes
* The Attribute Handler Interface::
* Accessing attributes from C::
Structural Properties of Graphs
* Basic Properties::
* Shortest Path Related Functions::
* Neighborhood of a vertex::
* Graph Components::
* Degree Sequences::
* Centrality Measures::
* Estimating Centrality Measures::
* Centralization::
* Similarity Measures::
* Spanning Trees::
* Transitivity or Clustering Coefficient::
* Directedness conversion::
* Spectral properties::
* Non-simple graphs; multiple and loop edges::
* Mixing patterns::
* K-Cores::
* Topological sorting, directed acyclic graphs: Topological sorting; directed acyclic graphs.
* Maximum cardinality search, graph decomposition, chordal graphs: Maximum cardinality search; graph decomposition; chordal graphs.
* Matchings::
* Line graphs::
* Unfolding a graph into a tree::
* Other Operations::
Graph visitors
* Breadth-first search::
* Depth-first search::
Cliques and Independent Vertex Sets
* Cliques::
* Independent Vertex Sets::
Graph Isomorphism
* The simple interface::
* The BLISS algorithm::
* The VF2 algorithm::
* The LAD algorithm::
* Functions for graphs with 3 or 4 vertices::
Graph Motifs, Dyad Census and Triad Census
* igraph_dyad_census --- Calculating the dyad census as defined by Holland and Leinhardt::
* igraph_triad_census --- Triad census, as defined by Davis and Leinhardt: igraph_triad_census --- Triad census; as defined by Davis and Leinhardt.
* Graph motifs::
Generating Layouts for Graph Drawing
* 2D layout generators::
* 3D layout generators::
* Merging layouts::
Reading and Writing Graphs from and to Files
* Simple edge list and similar formats::
* Binary formats::
* GraphML format::
* GML format::
* Pajek format::
* UCINET's DL file format::
* Graphviz format::
Maximum Flows, Minimum Cuts and related measures
* Maximum Flows::
* Cuts and minimum cuts::
* Connectivity::
* Edge- and Vertex-Disjoint Paths::
* Graph Adhesion and Cohesion::
* Cohesive Blocks::
Vertex separators
* igraph_is_separator --- Decides whether the removal of a set of vertices disconnects the graph::
* igraph_is_minimal_separator --- Decides whether a set of vertices is a minimal separator::
* igraph_all_minimal_st_separators --- List all vertex sets that are minimal (s,t) separators for some s and t: igraph_all_minimal_st_separators --- List all vertex sets that are minimal [s;t] separators for some s and t.
* igraph_minimum_size_separators --- Find all minimum size separating vertex sets::
Detecting Community Structure
* Common functions related to community structure::
* Community structure based on statistical mechanics::
* Community structure based on eigenvectors of matrices::
* Walktrap; community structure based on random walks::
* Edge betweenness based community detection::
* Community structure based on the optimization of modularity::
* Label propagation::
* The InfoMAP algorithm::
Graphlets
* Introduction: Introduction <1>.
* Performing graphlet decomposition::
Hierarchical random graphs
* Introduction: Introduction <2>.
* Representing HRGs::
* Fitting HRGs::
* HRG sampling::
* Conversion to and from igraph graphs::
* Predicting missing edges::
Spectral Coarse Graining
* Introduction: Introduction <3>.
* SCG functions::
Graph Operators
* Union and intersection::
* Other set-like operators::
Using BLAS, LAPACK and ARPACK for igraph matrices and graphs
* BLAS interface in igraph::
* LAPACK interface in igraph::
* ARPACK interface in igraph::
Bipartite, i.e. two-mode graphs
* Bipartite networks in igraph::
* Create two-mode networks::
* Incidence matrices::
* Project a two-mode graphs::
* Other operations on bipartite graphs::
Advanced igraph programming
* Using igraph in multi-threaded programs::
* Progress handlers::
* Status handlers::
Not Graph Related Functions
* Igraph version number::
* Running Mean of a Time Series::
* Random Sampling from Very Long Sequences::
* Convex hull of a set of points on a plane::
* Fitting power-law distributions to empirical data::
Licenses for igraph and this manual
* THE GNU GENERAL PUBLIC LICENSE::
* The GNU Free Documentation License::
File: igraph_reference_manual.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
1 Introduction
**************
This is another library for creating and manipulating graphs. You can
look at it two ways: first, igraph contains the implementation of quite
a lot graph algorithms. These include classic graph algorithms like
graph isomorphism, graph girth and connectivity and also the new wave
graph algorithms like transitivity, graph motifs and community
structure detection. Skim through the table of contents or the index of
this book to get an impression.
Second, igraph provides a platform for the developing and/or
implementing graph algorithms. It has a quite efficient data structure
for representing graphs and a number of other data structures like
flexible vectors, stacks, heaps, queues, adjacency lists to accomplish
this. In fact these data structures evolved along the implementation of
the classic and non-classic graph algorithms which make up the major
part of the igraph library. This way they were fine tuned and checked
for correctness several times.
Our main goal with developing igraph was to create a graph library
which is efficient on large but not extremely large graphs. More
precisely, it is assumed that the graph(s) fit into the physical memory
of the computer. Nowadays this means graphs with several million
vertices and/or edges. Our definition of efficient is that it runs
fast, both in theory and (more importantly) in practice.
We believe that one of the big strengths of igraph is that it can be
embedded into a higher level language or environment. Two such
embeddings (or interfaces if you look at them the other way) are
currently being developed by us: igraph as a GNU R package and igraph
as a Python extension module. A third embedding, being developed by
another developer is a Ruby extension. Other are likely to come. The
high level languages as R or Python make it possible to do use graph
routines with mush greater comfort, without actually writing a single
line of C code. They have some, usually very small, speed penalty
compared to the C version, but add ease and much flexibility. This
manual however covers only the C library. If you want to use Python or
GNU R, please see the documentation written specifically for these
interfaces and come back here only if you're interested in some detail
which is not covered in those documents.
We still consider igraph as a child project. It has much room for
development and we are sure that it will improve a lot in the near
future. Any feedback we can get from the users is very important for
us, as most of the time these questions and comments guide us in what
to add and what to improve.
igraph is open source and distributed under the terms of the GNU GPL.
We strongly believe that all the algorithms used in science, let that
be graph theory or not, should have an efficient open source
implementation allowing use and modification for anyone.
* Menu:
* igraph is free software::
* Citing igraph::
File: igraph_reference_manual.info, Node: igraph is free software, Next: Citing igraph, Up: Introduction
1.1 igraph is free software
===========================
igraph library
Copyright (C) 2003-2012 Gabor Csardi 334
Harvard st, Cambridge MA, 02139, USA
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
File: igraph_reference_manual.info, Node: Citing igraph, Prev: igraph is free software, Up: Introduction
1.2 Citing igraph
=================
To cite igraph in publications, please use the following reference:
Ga'bor Csa'rdi, Tama's Nepusz: The igraph software package for
complex network research. InterJournal Complex Systems, 1695, 2006.
File: igraph_reference_manual.info, Node: Installation, Next: Tutorial, Prev: Introduction, Up: Top
2 Installation
**************
The easiest way to install the igraph C library depends on your system,
and it might also change, so we no longer include installation
instructions here. Please see the igraph homepage at http://igraph.org
(http://igraph.org) instead.
File: igraph_reference_manual.info, Node: Tutorial, Next: About igraph graphs; the basic interface, Prev: Installation, Up: Top
3 Tutorial
**********
* Menu:
* Lesson 1. Compiling programs using igraph.: Lesson 1_ Compiling programs using igraph_.
* Lesson 2. Creating your first graphs.: Lesson 2_ Creating your first graphs_.
* Lesson 3. Calculating various properties of graphs.: Lesson 3_ Calculating various properties of graphs_.
File: igraph_reference_manual.info, Node: Lesson 1_ Compiling programs using igraph_, Next: Lesson 2_ Creating your first graphs_, Up: Tutorial
3.1 Lesson 1. Compiling programs using igraph.
==============================================
The following short example program demonstrates the basic usage of the
`igraph' library.
#include
int main(void)
{
igraph_integer_t diameter;
igraph_t graph;
igraph_rng_seed(igraph_rng_default(), 42);
igraph_erdos_renyi_game(&graph, IGRAPH_ERDOS_RENYI_GNP, 1000, 5.0/1000,
IGRAPH_UNDIRECTED, IGRAPH_NO_LOOPS);
igraph_diameter(&graph, &diameter, 0, 0, 0, IGRAPH_UNDIRECTED, 1);
printf("Diameter of a random graph with average degree 5: %d\n",
(int) diameter);
igraph_destroy(&graph);
return 0;
}
This example illustrates a couple of points. First, programs using
the `igraph' library should include the `igraph.h' header file. Second,
`igraph' uses the `igraph_real_t' type for real numbers instead of
`double'. Third, `igraph' graph objects are represented by the
`igraph_t' data type. Fourth, the `igraph_erdos_renyi_game()' creates a
graph and `igraph_destroy()' destroys it, ie. deallocates the memory
associated to it.
For compiling this program you need a C compiler, if this is called
`gcc' and the previous code is saved in file `igraph_test.c', you will
need a command like this:
gcc igraph_test.c -I/usr/local/igraph -L/usr/local/lib -ligraph -o igraph_test
The exact form depends on where `igraph' was installed on your
system. The directory after the `-I' switch is the one containing the
`igraph.h' file, while the one following `-L' should contain the
library file itself, usually a file called `libigraph.so',
`libigraph.a' or `igraph.dll'. It your system has the `pkg-config'
utility you are likely to get the neccessary compile options by issuing
the command
pkg-config --libs --cflags igraph
The executable can be run by simply typing its name like this:
./igraph_test
on most systems. If you use dynamic linking and the `igraph' libraries
are not at a standard place, you may need to set the `LD_LIBRARY_PATH'
variable, the syntax depends on the shell use are using. In `bash' it
goes like this:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/libs/igraph
./igraph_test
Here we assumed that the `igraph' library is installed in
`/home/user/libs/igraph'. Alternatively, you can use the `LD_PRELOAD'
variable to preload the `igraph' library before invoking your program:
LD_PRELOAD=/home/user/libs/igraph/libigraph.so ./igraph_test
Please note that `LD_PRELOAD' and `LD_LIBRARY_PATH' are usually
available only on Un*x-like systems. On Windows using Cygwin it is
usually enough to set the `PATH' enviroment variable to include the
folder in which the `igraph' library is installed, look for the
`cygigraph-0.dll' or similar file.
File: igraph_reference_manual.info, Node: Lesson 2_ Creating your first graphs_, Next: Lesson 3_ Calculating various properties of graphs_, Prev: Lesson 1_ Compiling programs using igraph_, Up: Tutorial
3.2 Lesson 2. Creating your first graphs.
=========================================
The functions generating graph objects are called graph generators.
Stochastic (=randomized) graph generators are called `games'.
`igraph' 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. Eg.
`igraph_shortest_paths()' which (surprisingly) calculates shortest
paths from a vertex to another vertices can calculate directed or
undirected paths.
`igraph' has sophisticated ways for creating graphs. The simplest
graphs are deterministic regular structures like star graphs
(`igraph_star()'), ring graphs (`igraph_ring()'), lattices
(`igraph_lattice()') or trees (`igraph_tree()').
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.)
#include
int main(void) {
igraph_real_t avg_path;
igraph_t graph;
igraph_vector_t dimvector;
igraph_vector_t edges;
int i;
igraph_vector_init(&dimvector, 2);
VECTOR(dimvector)[0]=30;
VECTOR(dimvector)[1]=30;
igraph_lattice(&graph, &dimvector, 0, IGRAPH_UNDIRECTED, 0, 1);
igraph_rng_seed(igraph_rng_default(), 42);
igraph_vector_init(&edges, 20);
for (i=0; i
int main(void) {
igraph_t graph;
igraph_vector_t v;
igraph_vector_t result;
igraph_real_t edges[] = { 0, 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 7, 0, 8,
0,10, 0,11, 0,12, 0,13, 0,17, 0,19, 0,21, 0,31,
1, 2, 1, 3, 1, 7, 1,13, 1,17, 1,19, 1,21, 1,30,
2, 3, 2, 7, 2,27, 2,28, 2,32, 2, 9, 2, 8, 2,13,
3, 7, 3,12, 3,13, 4, 6, 4,10, 5, 6, 5,10, 5,16,
6,16, 8,30, 8,32, 8,33, 9,33,13,33,14,32,14,33,
15,32,15,33,18,32,18,33,19,33,20,32,20,33,
22,32,22,33,23,25,23,27,23,32,23,33,23,29,
24,25,24,27,24,31,25,31,26,29,26,33,27,33,
28,31,28,33,29,32,29,33,30,32,30,33,31,32,31,33,
32,33
};
igraph_vector_view(&v, edges, sizeof(edges)/sizeof(double));
igraph_create(&graph, &v, 0, IGRAPH_UNDIRECTED);
igraph_vector_init(&result, 0);
igraph_degree(&graph, &result, igraph_vss_all(), IGRAPH_ALL,
IGRAPH_LOOPS);
printf("Maximum degree is %10i, vertex %2i.\n",
(int)igraph_vector_max(&result), (int)igraph_vector_which_max(&result));
igraph_closeness(&graph, &result, igraph_vss_all(), IGRAPH_ALL,
/*weights=*/ 0);
printf("Maximum closeness is %10f, vertex %2i.\n",
(double)igraph_vector_max(&result), (int)igraph_vector_which_max(&result));
igraph_betweenness(&graph, &result, igraph_vss_all(),
IGRAPH_UNDIRECTED, /*weights=*/ 0, /*nobigint=*/ 1);
printf("Maximum betweenness is %10f, vertex %2i.\n",
(double)igraph_vector_max(&result), (int)igraph_vector_which_max(&result));
igraph_vector_destroy(&result);
igraph_destroy(&graph);
return 0;
}
This example reflects some new features. First of all, it shows a
way to define a graph simply as defining a C array with its edges.
Function `igraph_vector_view()' creates a _view_ of a C array. It does
not copy any data, this also means that you should not call
`igraph_vector_destroy()' on a vector created this way. This vector is
then used to create the undirected graph.
Then the degree, closeness and betweenness centrality of the vertices
is calculated and the highest values are printed. Note that the vector
(`result') which returns the result from these functions has to be
initialized first, and also that the functions resize it to be able to
hold the result.
The `igraph_vss_all()' argument tells the functions to calculate the
property for every vertex in the graph, it is shorthand for a _vertex
selector_ (`igraph_vs_t'). Vertex selectors help performing operations
on a subset of vertices, you can read more about them in one of the
following chapters.
File: igraph_reference_manual.info, Node: About igraph graphs; the basic interface, Next: Error Handling, Prev: Tutorial, Up: Top
4 About igraph graphs, the basic interface
******************************************
* Menu:
* The igraph data model::
* The basic interface::
File: igraph_reference_manual.info, Node: The igraph data model, Next: The basic interface, Up: About igraph graphs; the basic interface
4.1 The igraph data model
=========================
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 are the number of vertices in
the graph and whether the graph is directed or undirected.
Like the edges, the igraph vertices are also labeled by number
between zero and the number of vertices minus one. So, to summarize, a
directed graph can be imagined like this:
( vertices: 6,
directed: yes,
{
(0,2),
(2,2),
(2,3),
(3,3),
(3,4),
(3,4),
(4,1)
}
)
Here the edges are ordered pairs or vertex ids, and the graph is a
multiset of edges plus some meta-data.
An undirected graph is like this:
( vertices: 6,
directed: no,
{
{0,2},
{2},
{2,3},
{3},
{3,4},
{3,4},
{4,1}
}
)
Here an edge is a set of one or two vertex ids, two for most of the
time, except for loop edges. A graph is a multiset of edges plus meta
data, just like in the directed case.
It is possible to convert a directed graph to an undirected one, see
the `igraph_to_directed()' (*note igraph_to_directed --- Convert an
undirected graph to a directed one::) and `igraph_to_undirected()'
(*note igraph_to_undirected --- Convert a directed graph to an
undirected one_::) functions.
Note that igraph has some limited support for graphs with multiple
edges. The support means that multiple edges can be stored in igraph
graphs, but for most functions (like `igraph_betweenness()' (*note
igraph_betweenness --- Betweenness centrality of some vertices_::)) it
is not checked that they work well on graphs with multiple edges. To
eliminate multiple edges from a graph, you can use `igraph_simplify()'
(*note igraph_simplify --- Removes loop and/or multiple edges from the
graph_::).
File: igraph_reference_manual.info, Node: The basic interface, Prev: The igraph data model, Up: About igraph graphs; the basic interface
4.2 The basic interface
=======================
This is the very minimal API in `igraph'. All the other functions use
this minimal set for creating and manipulating graphs.
This is a very important principle since it makes possible to
implement other data representations by implementing only this minimal
set.
* Menu:
* Graph Constructors and Destructors::
* Basic Query Operations::
* Adding and Deleting Vertices and Edges::
* Deprecated functions::
File: igraph_reference_manual.info, Node: Graph Constructors and Destructors, Next: Basic Query Operations, Up: The basic interface
4.2.1 Graph Constructors and Destructors
----------------------------------------
* Menu:
* igraph_empty --- Creates an empty graph with some vertices and no edges.: igraph_empty --- Creates an empty graph with some vertices and no edges_.
* igraph_empty_attrs --- Creates an empty graph with some vertices, no edges and some graph attributes.: igraph_empty_attrs --- Creates an empty graph with some vertices; no edges and some graph attributes_.
* igraph_copy --- Creates an exact (deep) copy of a graph.: igraph_copy --- Creates an exact [deep] copy of a graph_.
* igraph_destroy --- Frees the memory allocated for a graph object. : igraph_destroy --- Frees the memory allocated for a graph object_.
File: igraph_reference_manual.info, Node: igraph_empty --- Creates an empty graph with some vertices and no edges_, Next: igraph_empty_attrs --- Creates an empty graph with some vertices; no edges and some graph attributes_, Up: Graph Constructors and Destructors
4.2.1.1 igraph_empty -- Creates an empty graph with some vertices and no edges.
...............................................................................
int igraph_empty(igraph_t *graph, igraph_integer_t n, igraph_bool_t directed);
The most basic constructor, all the other constructors should call
this to create a minimal graph object. Our use of the term "empty graph"
in the above description should be distinguished from the mathematical
definition of the empty or null graph. Strictly speaking, the empty or
null graph in graph theory is the graph with no vertices and no edges.
However by "empty graph" as used in `igraph' we mean a graph having
zero or more vertices, but no edges.
*Arguments:. *
`graph':
Pointer to a not-yet initialized graph object.
`n':
The number of vertices in the graph, a non-negative integer number
is expected.
`directed':
Boolean; whether the graph is directed or not. Supported values
are:
`IGRAPH_DIRECTED'
The graph will be _directed._
`IGRAPH_UNDIRECTED'
The graph will be _undirected._
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of vertices.
Time complexity: O(|V|) for a graph with |V| vertices (and no edges).
* File examples/simple/igraph_empty.c*
File: igraph_reference_manual.info, Node: igraph_empty_attrs --- Creates an empty graph with some vertices; no edges and some graph attributes_, Next: igraph_copy --- Creates an exact [deep] copy of a graph_, Prev: igraph_empty --- Creates an empty graph with some vertices and no edges_, Up: Graph Constructors and Destructors
4.2.1.2 igraph_empty_attrs -- Creates an empty graph with some vertices, no edges and some graph attributes.
............................................................................................................
int igraph_empty_attrs(igraph_t *graph, igraph_integer_t n, igraph_bool_t directed, void* attr);
Use this instead of `igraph_empty()' (*note igraph_empty --- Creates
an empty graph with some vertices and no edges_::) if you wish to add
some graph attributes right after initialization. This function is
currently not very interesting for the ordinary user. Just supply 0
here or use `igraph_empty()' (*note igraph_empty --- Creates an empty
graph with some vertices and no edges_::).
*Arguments:. *
`graph':
Pointer to a not-yet initialized graph object.
`n':
The number of vertices in the graph; a non-negative integer number
is expected.
`directed':
Boolean; whether the graph is directed or not. Supported values
are:
`IGRAPH_DIRECTED'
Create a _directed_ graph.
`IGRAPH_UNDIRECTED'
Create an _undirected_ graph.
`attr':
The attributes.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of vertices.
Time complexity: O(|V|) for a graph with |V| vertices (and no edges).
File: igraph_reference_manual.info, Node: igraph_copy --- Creates an exact [deep] copy of a graph_, Next: igraph_destroy --- Frees the memory allocated for a graph object_, Prev: igraph_empty_attrs --- Creates an empty graph with some vertices; no edges and some graph attributes_, Up: Graph Constructors and Destructors
4.2.1.3 igraph_copy -- Creates an exact (deep) copy of a graph.
...............................................................
int igraph_copy(igraph_t *to, const igraph_t *from);
This function deeply copies a graph object to create an exact
replica of it. The new replica should be destroyed by calling
`igraph_destroy()' (*note igraph_destroy --- Frees the memory allocated
for a graph object_::) on it when not needed any more.
You can also create a shallow copy of a graph by simply using the
standard assignment operator, but be careful and do _not_ destroy a
shallow replica. To avoid this mistake, creating shallow copies is not
recommended.
*Arguments:. *
`to':
Pointer to an uninitialized graph object.
`from':
Pointer to the graph object to copy.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|) for a graph with |V| vertices and |E|
edges.
* File examples/simple/igraph_copy.c*
File: igraph_reference_manual.info, Node: igraph_destroy --- Frees the memory allocated for a graph object_, Prev: igraph_copy --- Creates an exact [deep] copy of a graph_, Up: Graph Constructors and Destructors
4.2.1.4 igraph_destroy -- Frees the memory allocated for a graph object.
........................................................................
int igraph_destroy(igraph_t *graph);
This function should be called for every graph object exactly once.
This function invalidates all iterators (of course), but the
iterators of a graph should be destroyed before the graph itself anyway.
*Arguments:. *
`graph':
Pointer to the graph to free.
*Returns:. *
`'
Error code.
Time complexity: operating system specific.
File: igraph_reference_manual.info, Node: Basic Query Operations, Next: Adding and Deleting Vertices and Edges, Prev: Graph Constructors and Destructors, Up: The basic interface
4.2.2 Basic Query Operations
----------------------------
* Menu:
* igraph_vcount --- The number of vertices in a graph.: igraph_vcount --- The number of vertices in a graph_.
* igraph_ecount --- The number of edges in a graph.: igraph_ecount --- The number of edges in a graph_.
* igraph_edge --- Gives the head and tail vertices of an edge.: igraph_edge --- Gives the head and tail vertices of an edge_.
* igraph_get_eid --- Get the edge id from the end points of an edge.: igraph_get_eid --- Get the edge id from the end points of an edge_.
* igraph_get_eids --- Return edge ids based on the adjacent vertices.: igraph_get_eids --- Return edge ids based on the adjacent vertices_.
* igraph_get_eids_multi --- Query edge ids based on their adjacent vertices, handle multiple edges.: igraph_get_eids_multi --- Query edge ids based on their adjacent vertices; handle multiple edges_.
* igraph_neighbors --- Adjacent vertices to a vertex.: igraph_neighbors --- Adjacent vertices to a vertex_.
* igraph_incident --- Gives the incident edges of a vertex.: igraph_incident --- Gives the incident edges of a vertex_.
* igraph_is_directed --- Is this a directed graph?::
* igraph_degree --- The degree of some vertices in a graph.: igraph_degree --- The degree of some vertices in a graph_.
File: igraph_reference_manual.info, Node: igraph_vcount --- The number of vertices in a graph_, Next: igraph_ecount --- The number of edges in a graph_, Up: Basic Query Operations
4.2.2.1 igraph_vcount -- The number of vertices in a graph.
...........................................................
igraph_integer_t igraph_vcount(const igraph_t *graph);
*Arguments:. *
`graph':
The graph.
*Returns:. *
`'
Number of vertices.
Time complexity: O(1)
File: igraph_reference_manual.info, Node: igraph_ecount --- The number of edges in a graph_, Next: igraph_edge --- Gives the head and tail vertices of an edge_, Prev: igraph_vcount --- The number of vertices in a graph_, Up: Basic Query Operations
4.2.2.2 igraph_ecount -- The number of edges in a graph.
........................................................
igraph_integer_t igraph_ecount(const igraph_t *graph);
*Arguments:. *
`graph':
The graph.
*Returns:. *
`'
Number of edges.
Time complexity: O(1)
File: igraph_reference_manual.info, Node: igraph_edge --- Gives the head and tail vertices of an edge_, Next: igraph_get_eid --- Get the edge id from the end points of an edge_, Prev: igraph_ecount --- The number of edges in a graph_, Up: Basic Query Operations
4.2.2.3 igraph_edge -- Gives the head and tail vertices of an edge.
...................................................................
int igraph_edge(const igraph_t *graph, igraph_integer_t eid,
igraph_integer_t *from, igraph_integer_t *to);
*Arguments:. *
`graph':
The graph object.
`eid':
The edge id.
`from':
Pointer to an `igraph_integer_t'. The tail of the edge will be
placed here.
`to':
Pointer to an `igraph_integer_t'. The head of the edge will be
placed here.
*Returns:. *
`'
Error code. The current implementation always returns with success.
*See also:. *
`'
`igraph_get_eid()' (*note igraph_get_eid --- Get the edge id from
the end points of an edge_::) for the opposite operation.
Added in version 0.2.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_get_eid --- Get the edge id from the end points of an edge_, Next: igraph_get_eids --- Return edge ids based on the adjacent vertices_, Prev: igraph_edge --- Gives the head and tail vertices of an edge_, Up: Basic Query Operations
4.2.2.4 igraph_get_eid -- Get the edge id from the end points of an edge.
.........................................................................
int igraph_get_eid(const igraph_t *graph, igraph_integer_t *eid,
igraph_integer_t pfrom, igraph_integer_t pto,
igraph_bool_t directed, igraph_bool_t error);
For undirected graphs `pfrom' and `pto' are exchangeable.
*Arguments:. *
`graph':
The graph object.
`eid':
Pointer to an integer, the edge id will be stored here.
`pfrom':
The starting point of the edge.
`pto':
The end point of the edge.
`directed':
Logical constant, whether to search for directed edges in a
directed graph. Ignored for undirected graphs.
`error':
Logical scalar, whether to report an error if the edge was not
found. If it is false, then -1 will be assigned to `eid'.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_edge()' (*note igraph_edge --- Gives the head and tail
vertices of an edge_::) for the opposite operation.
Time complexity: O(log (d)), where d is smaller of the out-degree of
`pfrom' and in-degree of `pto' if `directed' is true. If `directed' is
false, then it is O(log(d)+log(d2)), where d is the same as before and
d2 is the minimum of the out-degree of `pto' and the in-degree of
`pfrom'.
* File examples/simple/igraph_get_eid.c*
Added in version 0.2.
File: igraph_reference_manual.info, Node: igraph_get_eids --- Return edge ids based on the adjacent vertices_, Next: igraph_get_eids_multi --- Query edge ids based on their adjacent vertices; handle multiple edges_, Prev: igraph_get_eid --- Get the edge id from the end points of an edge_, Up: Basic Query Operations
4.2.2.5 igraph_get_eids -- Return edge ids based on the adjacent vertices.
..........................................................................
int igraph_get_eids(const igraph_t *graph, igraph_vector_t *eids,
const igraph_vector_t *pairs,
const igraph_vector_t *path,
igraph_bool_t directed, igraph_bool_t error);
This function operates in two modes. If the `pairs' argument is not
a null pointer, but the `path' argument is, then it searches for the
edge ids of all pairs of vertices given in `pairs'. The pairs of vertex
ids are taken consecutively from the vector, i.e. ` VECTOR(pairs)[0]'
and ` VECTOR(pairs)[1]' give the first pair, ` VECTOR(pairs)[2]' and
` VECTOR(pairs)[3]' the second pair, etc.
If the `pairs' argument is a null pointer, and `path' is not a null
pointer, then the `path' is interpreted as a path given by vertex ids
and the edges along the path are returned.
If neither `pairs' nor `path' are null pointers, then both are
considered (first `pairs' and then `path'), and the results are
concatenated.
If the `error' argument is true, then it is an error to give pairs
of vertices that are not connected. Otherwise -1 is reported for not
connected vertices.
If there are multiple edges in the graph, then these are ignored;
i.e. for a given pair of vertex ids, always the same edge id is
returned, even if the pair is given multiple time in `pairs' or in
`path'. See `igraph_get_eids_multi()' (*note igraph_get_eids_multi ---
Query edge ids based on their adjacent vertices; handle multiple
edges_::) for a similar function that works differently in case of
multiple edges.
*Arguments:. *
`graph':
The input graph.
`eids':
Pointer to an initialized vector, the result is stored here. It
will be resized as needed.
`pairs':
Vector giving pairs of vertices, or a null pointer.
`path':
Vector giving vertex ids along a path, or a null pointer.
`directed':
Logical scalar, whether to consider edge directions in directed
graphs. This is ignored for undirected graphs.
`error':
Logical scalar, whether it is an error to supply non-connected
vertices. If false, then -1 is returned for non-connected pairs.
*Returns:. *
`'
Error code.
Time complexity: O(n log(d)), where n is the number of queried edges
and d is the average degree of the vertices.
*See also:. *
`'
`igraph_get_eid()' (*note igraph_get_eid --- Get the edge id from
the end points of an edge_::) for a single edge,
`igraph_get_eids_multi()' (*note igraph_get_eids_multi --- Query
edge ids based on their adjacent vertices; handle multiple
edges_::) for a version that handles multiple edges better (at a
cost).
* File examples/simple/igraph_get_eids.c*
File: igraph_reference_manual.info, Node: igraph_get_eids_multi --- Query edge ids based on their adjacent vertices; handle multiple edges_, Next: igraph_neighbors --- Adjacent vertices to a vertex_, Prev: igraph_get_eids --- Return edge ids based on the adjacent vertices_, Up: Basic Query Operations
4.2.2.6 igraph_get_eids_multi -- Query edge ids based on their adjacent vertices, handle multiple edges.
........................................................................................................
int igraph_get_eids_multi(const igraph_t *graph, igraph_vector_t *eids,
const igraph_vector_t *pairs,
const igraph_vector_t *path,
igraph_bool_t directed, igraph_bool_t error);
This function operates in two modes. If the `pairs' argument is not
a null pointer, but the `path' argument is, then it searches for the
edge ids of all pairs of vertices given in `pairs'. The pairs of vertex
ids are taken consecutively from the vector, i.e. ` VECTOR(pairs)[0]'
and ` VECTOR(pairs)[1]' give the first pair, ` VECTOR(pairs)[2]' and
` VECTOR(pairs)[3]' the second pair, etc.
If the `pairs' argument is a null pointer, and `path' is not a null
pointer, then the `path' is interpreted as a path given by vertex ids
and the edges along the path are returned.
If the `error' argument is true, then it is an error to give pairs of
vertices that are not connected. Otherwise -1 is returned for not
connected vertex pairs.
An error is triggered if both `pairs' and `path' are non-null
pointers.
This function handles multiple edges properly, i.e. if the same pair
is given multiple times and they are indeed connected by multiple
edges, then each time a different edge id is reported.
*Arguments:. *
`graph':
The input graph.
`eids':
Pointer to an initialized vector, the result is stored here. It
will be resized as needed.
`pairs':
Vector giving pairs of vertices, or a null pointer.
`path':
Vector giving vertex ids along a path, or a null pointer.
`directed':
Logical scalar, whether to consider edge directions in directed
graphs. This is ignored for undirected graphs.
`error':
Logical scalar, whether to report an error if non-connected
vertices are specified. If false, then -1 is returned for
non-connected vertex pairs.
*Returns:. *
`'
Error code.
Time complexity: O(|E|+n log(d)), where |E| is the number of edges
in the graph, n is the number of queried edges and d is the average
degree of the vertices.
*See also:. *
`'
`igraph_get_eid()' (*note igraph_get_eid --- Get the edge id from
the end points of an edge_::) for a single edge,
`igraph_get_eids()' (*note igraph_get_eids --- Return edge ids
based on the adjacent vertices_::) for a faster version that does
not handle multiple edges.
File: igraph_reference_manual.info, Node: igraph_neighbors --- Adjacent vertices to a vertex_, Next: igraph_incident --- Gives the incident edges of a vertex_, Prev: igraph_get_eids_multi --- Query edge ids based on their adjacent vertices; handle multiple edges_, Up: Basic Query Operations
4.2.2.7 igraph_neighbors -- Adjacent vertices to a vertex.
..........................................................
int igraph_neighbors(const igraph_t *graph, igraph_vector_t *neis, igraph_integer_t pnode,
igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph to work on.
`neis':
This vector will contain the result. The vector should be
initialized beforehand and will be resized. Starting from igraph
version 0.4 this vector is always sorted, the vertex ids are in
increasing order.
`pnode':
The id of the node for which the adjacent vertices are to be
searched.
`mode':
Defines the way adjacent vertices are searched in directed graphs.
It can have the following values: `IGRAPH_OUT', vertices reachable
by an edge from the specified vertex are searched; `IGRAPH_IN',
vertices from which the specified vertex is reachable are searched;
`IGRAPH_ALL', both kinds of vertices are searched. This parameter
is ignored for undirected graphs.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
`IGRAPH_EINVMODE': invalid mode argument. `IGRAPH_ENOMEM': not
enough memory.
Time complexity: O(d), d is the number of adjacent vertices to the
queried vertex.
* File examples/simple/igraph_neighbors.c*
File: igraph_reference_manual.info, Node: igraph_incident --- Gives the incident edges of a vertex_, Next: igraph_is_directed --- Is this a directed graph?, Prev: igraph_neighbors --- Adjacent vertices to a vertex_, Up: Basic Query Operations
4.2.2.8 igraph_incident -- Gives the incident edges of a vertex.
................................................................
int igraph_incident(const igraph_t *graph, igraph_vector_t *eids,
igraph_integer_t pnode, igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph object.
`eids':
An initialized `vector_t' object. It will be resized to hold the
result.
`pnode':
A vertex id.
`mode':
Specifies what kind of edges to include for directed graphs.
`IGRAPH_OUT' means only outgoing edges, `IGRAPH_IN' only incoming
edges, `IGRAPH_ALL' both. This parameter is ignored for undirected
graphs.
*Returns:. *
`'
Error code. `IGRAPH_EINVVID': invalid `pnode' argument,
`IGRAPH_EINVMODE': invalid `mode' argument.
Added in version 0.2.
Time complexity: O(d), the number of incident edges to `pnode'.
File: igraph_reference_manual.info, Node: igraph_is_directed --- Is this a directed graph?, Next: igraph_degree --- The degree of some vertices in a graph_, Prev: igraph_incident --- Gives the incident edges of a vertex_, Up: Basic Query Operations
4.2.2.9 igraph_is_directed -- Is this a directed graph?
.......................................................
igraph_bool_t igraph_is_directed(const igraph_t *graph);
*Arguments:. *
`graph':
The graph.
*Returns:. *
`'
Logical value, ` TRUE' if the graph is directed, ` FALSE'
otherwise.
Time complexity: O(1)
* File examples/simple/igraph_is_directed.c*
File: igraph_reference_manual.info, Node: igraph_degree --- The degree of some vertices in a graph_, Prev: igraph_is_directed --- Is this a directed graph?, Up: Basic Query Operations
4.2.2.10 igraph_degree -- The degree of some vertices in a graph.
.................................................................
int igraph_degree(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids,
igraph_neimode_t mode, igraph_bool_t loops);
This function calculates the in-, out- or total degree of the
specified vertices.
*Arguments:. *
`graph':
The graph.
`res':
Vector, this will contain the result. It should be initialized and
will be resized to be the appropriate size.
`vids':
Vector, giving the vertex ids of which the degree will be
calculated.
`mode':
Defines the type of the degree. Valid modes are: `IGRAPH_OUT',
out-degree; `IGRAPH_IN', in-degree; `IGRAPH_ALL', total degree
(sum of the in- and out-degree). This parameter is ignored for
undirected graphs.
`loops':
Boolean, gives whether the self-loops should be counted.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
`IGRAPH_EINVMODE': invalid mode argument.
Time complexity: O(v) if loops is TRUE, and O(v*d) otherwise. v is
the number of vertices for which the degree will be calculated, and d
is their (average) degree.
*See also:. *
`'
`igraph_strength()' (*note igraph_strength --- Strength of the
vertices; weighted vertex degree in other words_::) for the
version that takes into account edge weights.
* File examples/simple/igraph_degree.c*
File: igraph_reference_manual.info, Node: Adding and Deleting Vertices and Edges, Next: Deprecated functions, Prev: Basic Query Operations, Up: The basic interface
4.2.3 Adding and Deleting Vertices and Edges
--------------------------------------------
* Menu:
* igraph_add_edge --- Adds a single edge to a graph.: igraph_add_edge --- Adds a single edge to a graph_.
* igraph_add_edges --- Adds edges to a graph object. : igraph_add_edges --- Adds edges to a graph object_.
* igraph_add_vertices --- Adds vertices to a graph. : igraph_add_vertices --- Adds vertices to a graph_.
* igraph_delete_edges --- Removes edges from a graph.: igraph_delete_edges --- Removes edges from a graph_.
* igraph_delete_vertices --- Removes vertices (with all their edges) from the graph.: igraph_delete_vertices --- Removes vertices [with all their edges] from the graph_.
File: igraph_reference_manual.info, Node: igraph_add_edge --- Adds a single edge to a graph_, Next: igraph_add_edges --- Adds edges to a graph object_, Up: Adding and Deleting Vertices and Edges
4.2.3.1 igraph_add_edge -- Adds a single edge to a graph.
.........................................................
int igraph_add_edge(igraph_t *graph, igraph_integer_t from, igraph_integer_t to);
For directed graphs the edge points from `from' to `to'.
Note that if you want to add many edges to a big graph, then it is
inefficient to add them one by one, it is better to collect them into a
vector and add all of them via a single `igraph_add_edges()' (*note
igraph_add_edges --- Adds edges to a graph object_::) call.
*Arguments:. *
`igraph':
The graph.
`from':
The id of the first vertex of the edge.
`to':
The id of the second vertex of the edge.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_add_edges()' (*note igraph_add_edges --- Adds edges to a
graph object_::) to add many edges, `igraph_delete_edges()' (*note
igraph_delete_edges --- Removes edges from a graph_::) to remove
edges and `igraph_add_vertices()' (*note igraph_add_vertices ---
Adds vertices to a graph_::) to add vertices.
Time complexity: O(|V|+|E|), the number of edges plus the number of
vertices.
File: igraph_reference_manual.info, Node: igraph_add_edges --- Adds edges to a graph object_, Next: igraph_add_vertices --- Adds vertices to a graph_, Prev: igraph_add_edge --- Adds a single edge to a graph_, Up: Adding and Deleting Vertices and Edges
4.2.3.2 igraph_add_edges -- Adds edges to a graph object.
.........................................................
int igraph_add_edges(igraph_t *graph, const igraph_vector_t *edges,
void *attr);
The edges are given in a vector, the first two elements define the
first edge (the order is ` from' , ` to' for directed graphs). The
vector should contain even number of integer numbers between zero and
the number of vertices in the graph minus one (inclusive). If you also
want to add new vertices, call igraph_add_vertices() first.
*Arguments:. *
`graph':
The graph to which the edges will be added.
`edges':
The edges themselves.
`attr':
The attributes of the new edges, only used by high level
interfaces currently, you can supply 0 here.
*Returns:. *
`'
Error code: `IGRAPH_EINVEVECTOR': invalid (odd) edges vector
length, `IGRAPH_EINVVID': invalid vertex id in edges vector.
This function invalidates all iterators.
Time complexity: O(|V|+|E|) where |V| is the number of vertices and
|E| is the number of edges in the _new,_ extended graph.
* File examples/simple/igraph_add_edges.c*
File: igraph_reference_manual.info, Node: igraph_add_vertices --- Adds vertices to a graph_, Next: igraph_delete_edges --- Removes edges from a graph_, Prev: igraph_add_edges --- Adds edges to a graph object_, Up: Adding and Deleting Vertices and Edges
4.2.3.3 igraph_add_vertices -- Adds vertices to a graph.
........................................................
int igraph_add_vertices(igraph_t *graph, igraph_integer_t nv, void *attr);
This function invalidates all iterators.
*Arguments:. *
`graph':
The graph object to extend.
`nv':
Non-negative integer giving the number of vertices to add.
`attr':
The attributes of the new vertices, only used by high level
interfaces, you can supply 0 here.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of new vertices.
Time complexity: O(|V|) where |V| is the number of vertices in the
_new,_ extended graph.
* File examples/simple/igraph_add_vertices.c*
File: igraph_reference_manual.info, Node: igraph_delete_edges --- Removes edges from a graph_, Next: igraph_delete_vertices --- Removes vertices [with all their edges] from the graph_, Prev: igraph_add_vertices --- Adds vertices to a graph_, Up: Adding and Deleting Vertices and Edges
4.2.3.4 igraph_delete_edges -- Removes edges from a graph.
..........................................................
int igraph_delete_edges(igraph_t *graph, igraph_es_t edges);
The edges to remove are given as an edge selector.
This function cannot remove vertices, they will be kept, even if
they lose all their edges.
This function invalidates all iterators.
*Arguments:. *
`graph':
The graph to work on.
`edges':
The edges to remove.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|) where |V| and |E| are the number of
vertices and edges in the _original_ graph, respectively.
* File examples/simple/igraph_delete_edges.c*
File: igraph_reference_manual.info, Node: igraph_delete_vertices --- Removes vertices [with all their edges] from the graph_, Prev: igraph_delete_edges --- Removes edges from a graph_, Up: Adding and Deleting Vertices and Edges
4.2.3.5 igraph_delete_vertices -- Removes vertices (with all their edges) from the graph.
.........................................................................................
int igraph_delete_vertices(igraph_t *graph, const igraph_vs_t vertices);
This function changes the ids of the vertices (except in some very
special cases, but these should not be relied on anyway).
This function invalidates all iterators.
*Arguments:. *
`graph':
The graph to work on.
`vertices':
The ids of the vertices to remove in a vector. The vector may
contain the same id more than once.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the original graph.
* File examples/simple/igraph_delete_vertices.c*
File: igraph_reference_manual.info, Node: Deprecated functions, Prev: Adding and Deleting Vertices and Edges, Up: The basic interface
4.2.4 Deprecated functions
--------------------------
* Menu:
* igraph_adjacent --- Gives the incident edges of a vertex.: igraph_adjacent --- Gives the incident edges of a vertex_.
File: igraph_reference_manual.info, Node: igraph_adjacent --- Gives the incident edges of a vertex_, Up: Deprecated functions
4.2.4.1 igraph_adjacent -- Gives the incident edges of a vertex.
................................................................
int igraph_adjacent(const igraph_t *graph, igraph_vector_t *eids,
igraph_integer_t pnode, igraph_neimode_t mode);
This function was superseded by `igraph_incident()' (*note
igraph_incident --- Gives the incident edges of a vertex_::) in igraph
0.6. Please use `igraph_incident()' (*note igraph_incident --- Gives
the incident edges of a vertex_::) instead of this function.
Added in version 0.2, deprecated in version 0.6.
File: igraph_reference_manual.info, Node: Error Handling, Next: Memory [de]allocation, Prev: About igraph graphs; the basic interface, Up: Top
5 Error Handling
****************
* Menu:
* Error handling basics::
* Error handlers::
* Error codes::
* Warning messages::
* Advanced topics::
File: igraph_reference_manual.info, Node: Error handling basics, Next: Error handlers, Up: Error Handling
5.1 Error handling basics
=========================
`igraph' functions can run into various problems preventing them from
normal operation. The user might have supplied invalid arguments, e.g.
a non-square matrix when a square-matrix was expected, or the program
has run out of memory while some more memory allocation is required,
etc.
By default `igraph' aborts the program when it runs into an error.
While this behavior might be good enough for smaller programs, it is
without doubt avoidable in larger projects. Please read further if your
project requires more sophisticated error handling. You can safely skip
the rest of this chapter otherwise.
File: igraph_reference_manual.info, Node: Error handlers, Next: Error codes, Prev: Error handling basics, Up: Error Handling
5.2 Error handlers
==================
If `igraph' runs into an error - an invalid argument was supplied to a
function, or we've ran out of memory - the control is transferred to
the _ error handler _ function.
The default error handler is `igraph_error_handler_abort' (*note
igraph_error_handler_abort --- Abort program in case of error_::) which
prints an error message and aborts the program.
The `igraph_set_error_handler()' (*note igraph_set_error_handler ---
Set a new error handler_::) function can be used to set a new error
handler function of type `igraph_error_handler_t' (*note
igraph_error_handler_t --- Type of error handler functions_::); see the
documentation of this type for details.
There are two other predefined error handler functions,
`igraph_error_handler_ignore' (*note igraph_error_handler_ignore ---
Ignore errors_::) and `igraph_error_handler_printignore' (*note
igraph_error_handler_printignore --- Print and ignore errors_::).
These deallocate the temporarily allocated memory (more about this
later) and return with the error code. The latter also prints an error
message. If you use these error handlers you need to take care about
possible errors yourself by checking the return value of (almost) every
non-void `igraph' function.
Independently of the error handler installed, all functions in the
library do their best to leave their arguments _semantically_ unchanged
if an error happens. By semantically we mean that the implementation of
an object supplied as an argument might change, but its `meaning' in
most cases does not. The rare occasions when this rule is violated are
documented in this manual.
* Menu:
* igraph_error_handler_t --- Type of error handler functions.: igraph_error_handler_t --- Type of error handler functions_.
* igraph_error_handler_abort --- Abort program in case of error.: igraph_error_handler_abort --- Abort program in case of error_.
* igraph_error_handler_ignore --- Ignore errors.: igraph_error_handler_ignore --- Ignore errors_.
* igraph_error_handler_printignore --- Print and ignore errors.: igraph_error_handler_printignore --- Print and ignore errors_.
File: igraph_reference_manual.info, Node: igraph_error_handler_t --- Type of error handler functions_, Next: igraph_error_handler_abort --- Abort program in case of error_, Up: Error handlers
5.2.1 igraph_error_handler_t -- Type of error handler functions.
----------------------------------------------------------------
typedef void igraph_error_handler_t (const char * reason, const char * file,
int line, int igraph_errno);
This is the type of the error handler functions.
*Arguments:. *
`reason':
Textual description of the error.
`file':
The source file in which the error is noticed.
`line':
The number of the line in the source file which triggered the error
`igraph_errno':
The `igraph' error code.
File: igraph_reference_manual.info, Node: igraph_error_handler_abort --- Abort program in case of error_, Next: igraph_error_handler_ignore --- Ignore errors_, Prev: igraph_error_handler_t --- Type of error handler functions_, Up: Error handlers
5.2.2 igraph_error_handler_abort -- Abort program in case of error.
-------------------------------------------------------------------
extern igraph_error_handler_t igraph_error_handler_abort;
The default error handler, prints an error message and aborts the
program.
File: igraph_reference_manual.info, Node: igraph_error_handler_ignore --- Ignore errors_, Next: igraph_error_handler_printignore --- Print and ignore errors_, Prev: igraph_error_handler_abort --- Abort program in case of error_, Up: Error handlers
5.2.3 igraph_error_handler_ignore -- Ignore errors.
---------------------------------------------------
extern igraph_error_handler_t igraph_error_handler_ignore;
This error handler frees the temporarily allocated memory and returns
with the error code.
File: igraph_reference_manual.info, Node: igraph_error_handler_printignore --- Print and ignore errors_, Prev: igraph_error_handler_ignore --- Ignore errors_, Up: Error handlers
5.2.4 igraph_error_handler_printignore -- Print and ignore errors.
------------------------------------------------------------------
extern igraph_error_handler_t igraph_error_handler_printignore;
Frees temporarily allocated memory, prints an error message to the
standard error and returns with the error code.
File: igraph_reference_manual.info, Node: Error codes, Next: Warning messages, Prev: Error handlers, Up: Error Handling
5.3 Error codes
===============
Every `igraph' function which can fail return a single integer error
code. Some functions are very simple and cannot run into any error,
these may return other types, or `void' as well. The error codes are
defined by the `igraph_error_type_t' (*note igraph_error_type_t ---
Error code type_::) enumeration.
* Menu:
* igraph_error_type_t --- Error code type.: igraph_error_type_t --- Error code type_.
* igraph_strerror --- Textual description of an error.: igraph_strerror --- Textual description of an error_.
File: igraph_reference_manual.info, Node: igraph_error_type_t --- Error code type_, Next: igraph_strerror --- Textual description of an error_, Up: Error codes
5.3.1 igraph_error_type_t -- Error code type.
---------------------------------------------
typedef enum {
IGRAPH_SUCCESS = 0,
IGRAPH_FAILURE = 1,
IGRAPH_ENOMEM = 2,
IGRAPH_PARSEERROR = 3,
IGRAPH_EINVAL = 4,
IGRAPH_EXISTS = 5,
IGRAPH_EINVEVECTOR = 6,
IGRAPH_EINVVID = 7,
IGRAPH_NONSQUARE = 8,
IGRAPH_EINVMODE = 9,
IGRAPH_EFILE = 10,
IGRAPH_UNIMPLEMENTED = 12,
IGRAPH_INTERRUPTED = 13,
IGRAPH_DIVERGED = 14,
IGRAPH_ARPACK_PROD = 15,
IGRAPH_ARPACK_NPOS = 16,
IGRAPH_ARPACK_NEVNPOS = 17,
IGRAPH_ARPACK_NCVSMALL = 18,
IGRAPH_ARPACK_NONPOSI = 19,
IGRAPH_ARPACK_WHICHINV = 20,
IGRAPH_ARPACK_BMATINV = 21,
IGRAPH_ARPACK_WORKLSMALL= 22,
IGRAPH_ARPACK_TRIDERR = 23,
IGRAPH_ARPACK_ZEROSTART = 24,
IGRAPH_ARPACK_MODEINV = 25,
IGRAPH_ARPACK_MODEBMAT = 26,
IGRAPH_ARPACK_ISHIFT = 27,
IGRAPH_ARPACK_NEVBE = 28,
IGRAPH_ARPACK_NOFACT = 29,
IGRAPH_ARPACK_FAILED = 30,
IGRAPH_ARPACK_HOWMNY = 31,
IGRAPH_ARPACK_HOWMNYS = 32,
IGRAPH_ARPACK_EVDIFF = 33,
IGRAPH_ARPACK_SHUR = 34,
IGRAPH_ARPACK_LAPACK = 35,
IGRAPH_ARPACK_UNKNOWN = 36,
IGRAPH_ENEGLOOP = 37,
IGRAPH_EINTERNAL = 38,
IGRAPH_ARPACK_MAXIT = 39,
IGRAPH_ARPACK_NOSHIFT = 40,
IGRAPH_ARPACK_REORDER = 41,
IGRAPH_EDIVZERO = 42,
IGRAPH_GLP_EBOUND = 43,
IGRAPH_GLP_EROOT = 44,
IGRAPH_GLP_ENOPFS = 45,
IGRAPH_GLP_ENODFS = 46,
IGRAPH_GLP_EFAIL = 47,
IGRAPH_GLP_EMIPGAP = 48,
IGRAPH_GLP_ETMLIM = 49,
IGRAPH_GLP_ESTOP = 50,
IGRAPH_EATTRIBUTES = 51,
IGRAPH_EATTRCOMBINE = 52,
IGRAPH_ELAPACK = 53,
IGRAPH_EDRL = 54,
IGRAPH_EOVERFLOW = 55,
IGRAPH_EGLP = 56,
IGRAPH_CPUTIME = 57,
IGRAPH_EUNDERFLOW = 58
} igraph_error_type_t;
These are the possible values returned by `igraph' functions. Note
that these are interesting only if you defined an error handler with
`igraph_set_error_handler()' (*note igraph_set_error_handler --- Set a
new error handler_::). Otherwise the program is aborted and the
function causing the error never returns.
*Values:. *
`IGRAPH_SUCCESS':
The function successfully completed its task.
`IGRAPH_FAILURE':
Something went wrong. You'll almost never meet this error as
normally more specific error codes are used.
`IGRAPH_ENOMEM':
There wasn't enough memory to allocate on the heap.
`IGRAPH_PARSEERROR':
A parse error was found in a file.
`IGRAPH_EINVAL':
A parameter's value is invalid. Eg. negative number was specified
as the number of vertices.
`IGRAPH_EXISTS':
A graph/vertex/edge attribute is already installed with the given
name.
`IGRAPH_EINVEVECTOR':
Invalid vector of vertex ids. A vertex id is either negative or
bigger than the number of vertices minus one.
`IGRAPH_EINVVID':
Invalid vertex id, negative or too big.
`IGRAPH_NONSQUARE':
A non-square matrix was received while a square matrix was
expected.
`IGRAPH_EINVMODE':
Invalid mode parameter.
`IGRAPH_EFILE':
A file operation failed. Eg. a file doesn't exist, or the user has
no rights to open it.
`IGRAPH_UNIMPLEMENTED':
Attempted to call an unimplemented or disabled (at compile-time)
function.
`IGRAPH_DIVERGED':
A numeric algorithm failed to converge.
`IGRAPH_ARPACK_PROD':
Matrix-vector product failed.
`IGRAPH_ARPACK_NPOS':
N must be positive.
`IGRAPH_ARPACK_NEVNPOS':
NEV must be positive.
`IGRAPH_ARPACK_NCVSMALL':
NCV must be bigger.
`IGRAPH_ARPACK_NONPOSI':
Maximum number of iterations should be positive.
`IGRAPH_ARPACK_WHICHINV':
Invalid WHICH parameter.
`IGRAPH_ARPACK_BMATINV':
Invalid BMAT parameter.
`IGRAPH_ARPACK_WORKLSMALL':
WORKL is too small.
`IGRAPH_ARPACK_TRIDERR':
LAPACK error in tridiagonal eigenvalue calculation.
`IGRAPH_ARPACK_ZEROSTART':
Starting vector is zero.
`IGRAPH_ARPACK_MODEINV':
MODE is invalid.
`IGRAPH_ARPACK_MODEBMAT':
MODE and BMAT are not compatible.
`IGRAPH_ARPACK_ISHIFT':
ISHIFT must be 0 or 1.
`IGRAPH_ARPACK_NEVBE':
NEV and WHICH='BE' are incompatible.
`IGRAPH_ARPACK_NOFACT':
Could not build an Arnoldi factorization.
`IGRAPH_ARPACK_FAILED':
No eigenvalues to sufficient accuracy.
`IGRAPH_ARPACK_HOWMNY':
HOWMNY is invalid.
`IGRAPH_ARPACK_HOWMNYS':
HOWMNY='S' is not implemented.
`IGRAPH_ARPACK_EVDIFF':
Different number of converged Ritz values.
`IGRAPH_ARPACK_SHUR':
Error from calculation of a real Schur form.
`IGRAPH_ARPACK_LAPACK':
LAPACK (dtrevc) error for calculating eigenvectors.
`IGRAPH_ARPACK_UNKNOWN':
Unknown ARPACK error.
`IGRAPH_ENEGLOOP':
Negative loop detected while calculating shortest paths.
`IGRAPH_EINTERNAL':
Internal error, likely a bug in igraph.
`IGRAPH_EDIVZERO':
Big integer division by zero.
`IGARPH_GLP_EBOUND':
GLPK error (GLP_EBOUND).
`IGARPH_GLP_EROOT':
GLPK error (GLP_EROOT).
`IGARPH_GLP_ENOPFS':
GLPK error (GLP_ENOPFS).
`IGARPH_GLP_ENODFS':
GLPK error (GLP_ENODFS).
`IGARPH_GLP_EFAIL':
GLPK error (GLP_EFAIL).
`IGARPH_GLP_EMIPGAP':
GLPK error (GLP_EMIPGAP).
`IGARPH_GLP_ETMLIM':
GLPK error (GLP_ETMLIM).
`IGARPH_GLP_ESTOP':
GLPK error (GLP_ESTOP).
`IGRAPH_EATTRIBUTES':
Attribute handler error. The user is not expected to find this; it
is signalled if some igraph function is not using the attribute
handler interface properly.
`IGRAPH_EATTRCOMBINE':
Unimplemented attribute combination method for the given attribute
type.
`IGRAPH_ELAPACK':
A LAPACK call resulted an error.
`IGRAPH_EDRL':
Internal error in the DrL layout generator.
`IGRAPH_EOVERFLOW':
Integer or double overflow.
`IGRAPH_EGLP':
Internal GLPK error.
`IGRAPH_CPUTIME':
CPU time exceeded.
`IGRAPH_EUNDERFLOW':
Integer or double underflow.
File: igraph_reference_manual.info, Node: igraph_strerror --- Textual description of an error_, Prev: igraph_error_type_t --- Error code type_, Up: Error codes
5.3.2 igraph_strerror -- Textual description of an error.
---------------------------------------------------------
const char* igraph_strerror(const int igraph_errno);
This is a simple utility function, it gives a short general textual
description for an `igraph' error code.
*Arguments:. *
`igraph_errno':
The `igraph' error code.
*Returns:. *
`'
pointer to the textual description of the error code.
File: igraph_reference_manual.info, Node: Warning messages, Next: Advanced topics, Prev: Error codes, Up: Error Handling
5.4 Warning messages
====================
Igraph also supports warning messages in addition to error messages.
Warning messages typically do not terminate the program, but they are
usually crucial to the user.
Igraph warning are handled similarly to errors. There is a separate
warning handler function that is called whenever an igraph function
triggers a warning. This handler can be set by the
`igraph_set_warning_handler()' (*note igraph_set_warning_handler ---
Install a warning handler::) function. There are two predefined simple
warning handlers, `igraph_warning_handler_ignore()' (*note
igraph_warning_handler_ignore --- Ignore all warnings::) and
`igraph_warning_handler_print()' (*note igraph_warning_handler_print
--- Print all warning to the standard error::), the latter being the
default.
To trigger a warning, igraph functions typically use the
`IGRAPH_WARNING()' (*note IGRAPH_WARNING --- Trigger a warning_::)
macro, the `igraph_warning()' (*note igraph_warning --- Trigger a
warning::) function, or if more flexibility is needed,
`igraph_warningf()' (*note igraph_warningf --- Trigger a warning; more
flexible printf-like syntax::).
* Menu:
* igraph_warning_handler_t --- Type of igraph warning handler functions::
* igraph_set_warning_handler --- Install a warning handler::
* IGRAPH_WARNING --- Trigger a warning.: IGRAPH_WARNING --- Trigger a warning_.
* igraph_warning --- Trigger a warning::
* igraph_warningf --- Trigger a warning, more flexible printf-like syntax: igraph_warningf --- Trigger a warning; more flexible printf-like syntax.
* igraph_warning_handler_ignore --- Ignore all warnings::
* igraph_warning_handler_print --- Print all warning to the standard error::
File: igraph_reference_manual.info, Node: igraph_warning_handler_t --- Type of igraph warning handler functions, Next: igraph_set_warning_handler --- Install a warning handler, Up: Warning messages
5.4.1 igraph_warning_handler_t -- Type of igraph warning handler functions
--------------------------------------------------------------------------
typedef igraph_error_handler_t igraph_warning_handler_t;
Currently it is defined to have the same type as
`igraph_error_handler_t' (*note igraph_error_handler_t --- Type of
error handler functions_::), although the last (error code) argument is
not used.
File: igraph_reference_manual.info, Node: igraph_set_warning_handler --- Install a warning handler, Next: IGRAPH_WARNING --- Trigger a warning_, Prev: igraph_warning_handler_t --- Type of igraph warning handler functions, Up: Warning messages
5.4.2 igraph_set_warning_handler -- Install a warning handler
-------------------------------------------------------------
igraph_warning_handler_t*
igraph_set_warning_handler(igraph_warning_handler_t* new_handler);
Install the supplied warning handler function.
*Arguments:. *
`new_handler':
The new warning handler function to install. Supply a null
pointer here to uninstall the current warning handler, without
installing a new one.
*Returns:. *
`'
The current warning handler function.
File: igraph_reference_manual.info, Node: IGRAPH_WARNING --- Trigger a warning_, Next: igraph_warning --- Trigger a warning, Prev: igraph_set_warning_handler --- Install a warning handler, Up: Warning messages
5.4.3 IGRAPH_WARNING -- Trigger a warning.
------------------------------------------
#define IGRAPH_WARNING(reason)
This is the usual way of triggering a warning from an igraph
function. It calls `igraph_warning()' (*note igraph_warning --- Trigger
a warning::).
*Arguments:. *
`reason':
The warning message.
File: igraph_reference_manual.info, Node: igraph_warning --- Trigger a warning, Next: igraph_warningf --- Trigger a warning; more flexible printf-like syntax, Prev: IGRAPH_WARNING --- Trigger a warning_, Up: Warning messages
5.4.4 igraph_warning -- Trigger a warning
-----------------------------------------
int igraph_warning(const char *reason, const char *file, int line,
int igraph_errno);
Call this function if you want to trigger a warning from within a
function that uses igraph.
*Arguments:. *
`reason':
Textual description of the warning.
`file':
The source file in which the warning was noticed.
`line':
The number of line in the source file which triggered the warning.
`igraph_errno':
Warnings could have potentially error codes as well, but this is
currently not used in igraph.
*Returns:. *
`'
The supplied error code.
File: igraph_reference_manual.info, Node: igraph_warningf --- Trigger a warning; more flexible printf-like syntax, Next: igraph_warning_handler_ignore --- Ignore all warnings, Prev: igraph_warning --- Trigger a warning, Up: Warning messages
5.4.5 igraph_warningf -- Trigger a warning, more flexible printf-like syntax
----------------------------------------------------------------------------
int igraph_warningf(const char *reason, const char *file, int line,
int igraph_errno, ...);
This function is similar to `igraph_warning()' (*note igraph_warning
--- Trigger a warning::), but uses a printf-like syntax. It substitutes
the additional arguments into the `reason' template string and calls
`igraph_warning()' (*note igraph_warning --- Trigger a warning::).
*Arguments:. *
`reason':
Textual description of the warning, a template string with the
same syntax as the standard printf C library function.
`file':
The source file in which the warning was noticed.
`line':
The number of line in the source file which triggered the warning.
`igraph_errno':
Warnings could have potentially error codes as well, but this is
currently not used in igraph.
`...':
The additional arguments to be substituted into the template
string.
*Returns:. *
`'
The supplied error code.
File: igraph_reference_manual.info, Node: igraph_warning_handler_ignore --- Ignore all warnings, Next: igraph_warning_handler_print --- Print all warning to the standard error, Prev: igraph_warningf --- Trigger a warning; more flexible printf-like syntax, Up: Warning messages
5.4.6 igraph_warning_handler_ignore -- Ignore all warnings
----------------------------------------------------------
void igraph_warning_handler_ignore (const char *reason, const char *file,
int line, int igraph_errno);
This warning handler function simply ignores all warnings.
*Arguments:. *
`reason':
Textual description of the warning.
`file':
The source file in which the warning was noticed.
`line':
The number of line in the source file which triggered the warning..
`igraph_errno':
Warnings could have potentially error codes as well, but this is
currently not used in igraph.
File: igraph_reference_manual.info, Node: igraph_warning_handler_print --- Print all warning to the standard error, Prev: igraph_warning_handler_ignore --- Ignore all warnings, Up: Warning messages
5.4.7 igraph_warning_handler_print -- Print all warning to the standard error
-----------------------------------------------------------------------------
void igraph_warning_handler_print (const char *reason, const char *file,
int line, int igraph_errno);
This warning handler function simply prints all warnings to the
standard error.
*Arguments:. *
`reason':
Textual description of the warning.
`file':
The source file in which the warning was noticed.
`line':
The number of line in the source file which triggered the warning..
`igraph_errno':
Warnings could have potentially error codes as well, but this is
currently not used in igraph.
File: igraph_reference_manual.info, Node: Advanced topics, Prev: Warning messages, Up: Error Handling
5.5 Advanced topics
===================
* Menu:
* Writing error handlers::
* Error handling internals::
* Deallocating memory::
* Writing igraph functions with proper error handling::
* Error handling and threads::
File: igraph_reference_manual.info, Node: Writing error handlers, Next: Error handling internals, Up: Advanced topics
5.5.1 Writing error handlers
----------------------------
The contents of the rest of this chapter might be useful only for those
who want to create an interface to `igraph' from another language. Most
readers can safely skip to the next chapter.
You can write and install error handlers simply by defining a
function of type `igraph_error_handler_t' (*note igraph_error_handler_t
--- Type of error handler functions_::) and calling
`igraph_set_error_handler()' (*note igraph_set_error_handler --- Set a
new error handler_::). This feature is useful for interface writers, as
`igraph' will have the chance to signal errors the appropriate way, eg.
the R interface defines an error handler which calls the `error()'
function, as required by R, while the Python interface has an error
handler which raises an exception according to the Python way.
If you want to write an error handler, your error handler should
call `IGRAPH_FINALLY_FREE()' (*note IGRAPH_FINALLY_FREE --- Deallocate
all registered objects_::) to deallocate all temporary memory to
prevent memory leaks.
* Menu:
* igraph_set_error_handler --- Set a new error handler.: igraph_set_error_handler --- Set a new error handler_.
File: igraph_reference_manual.info, Node: igraph_set_error_handler --- Set a new error handler_, Up: Writing error handlers
5.5.1.1 igraph_set_error_handler -- Set a new error handler.
............................................................
igraph_error_handler_t*
igraph_set_error_handler(igraph_error_handler_t* new_handler);
Installs a new error handler. If called with 0, it installs the
default error handler (which is currently `igraph_error_handler_abort'
(*note igraph_error_handler_abort --- Abort program in case of
error_::)).
*Arguments:. *
`new_handler':
The error handler function to install.
*Returns:. *
`'
The old error handler function. This should be saved and restored
if `new_handler' is not needed any more.
File: igraph_reference_manual.info, Node: Error handling internals, Next: Deallocating memory, Prev: Writing error handlers, Up: Advanced topics
5.5.2 Error handling internals
------------------------------
If an error happens, the functions in the library call the
`IGRAPH_ERROR' (*note IGRAPH_ERROR --- Trigger an error_::) macro with
a textual description of the error and an `igraph' error code. This
macro calls (through the `igraph_error()' (*note igraph_error ---
Trigger an error_::) function) the installed error handler. Another
useful macro is `IGRAPH_CHECK()' (*note IGRAPH_CHECK --- Check the
return value of a function call_::). This checks the return value of its
argument, which is normally a function call, and calls `IGRAPH_ERROR'
(*note IGRAPH_ERROR --- Trigger an error_::) if it is not
`IGRAPH_SUCCESS'.
* Menu:
* IGRAPH_ERROR --- Trigger an error.: IGRAPH_ERROR --- Trigger an error_.
* igraph_error --- Trigger an error.: igraph_error --- Trigger an error_.
* igraph_errorf --- Trigger an error, printf-like version.: igraph_errorf --- Trigger an error; printf-like version_.
* IGRAPH_CHECK --- Check the return value of a function call.: IGRAPH_CHECK --- Check the return value of a function call_.
File: igraph_reference_manual.info, Node: IGRAPH_ERROR --- Trigger an error_, Next: igraph_error --- Trigger an error_, Up: Error handling internals
5.5.2.1 IGRAPH_ERROR -- Trigger an error.
.........................................
#define IGRAPH_ERROR(reason,igraph_errno)
`igraph' functions usually use this macro when they notice an error.
It calls `igraph_error()' (*note igraph_error --- Trigger an error_::)
with the proper parameters and if that returns the macro returns the
"calling" function as well, with the error code. If for some
(suspicious) reason you want to call the error handler without
returning from the current function, call `igraph_error()' (*note
igraph_error --- Trigger an error_::) directly.
*Arguments:. *
`reason':
Textual description of the error. This should be something more
descriptive than the text associated with the error code. Eg. if
the error code is `IGRAPH_EINVAL', its associated text (see
`igraph_strerror()' (*note igraph_strerror --- Textual description
of an error_::)) is "Invalid value" and this string should explain
which parameter was invalid and maybe why.
`igraph_errno':
The `igraph' error code.
File: igraph_reference_manual.info, Node: igraph_error --- Trigger an error_, Next: igraph_errorf --- Trigger an error; printf-like version_, Prev: IGRAPH_ERROR --- Trigger an error_, Up: Error handling internals
5.5.2.2 igraph_error -- Trigger an error.
.........................................
int igraph_error(const char *reason, const char *file, int line,
int igraph_errno);
`igraph' functions usually call this function (most often via the
`IGRAPH_ERROR' (*note IGRAPH_ERROR --- Trigger an error_::) macro) if
they notice an error. It calls the currently installed error handler
function with the supplied arguments.
*Arguments:. *
`reason':
Textual description of the error.
`file':
The source file in which the error was noticed.
`line':
The number of line in the source file which triggered the error.
`igraph_errno':
The `igraph' error code.
*Returns:. *
`'
the error code (if it returns)
*See also:. *
`'
igraph_errorf().
File: igraph_reference_manual.info, Node: igraph_errorf --- Trigger an error; printf-like version_, Next: IGRAPH_CHECK --- Check the return value of a function call_, Prev: igraph_error --- Trigger an error_, Up: Error handling internals
5.5.2.3 igraph_errorf -- Trigger an error, printf-like version.
...............................................................
int igraph_errorf(const char *reason, const char *file, int line,
int igraph_errno, ...);
*Arguments:. *
`reason':
Textual description of the error, interpreted as a printf format
string.
`file':
The source file in which the error was noticed.
`line':
The line in the source file which triggered the error.
`igraph_errno':
The `igraph' error code.
`...':
Additional parameters, the values to substitute into the format
string.
*See also:. *
`'
igraph_error().
File: igraph_reference_manual.info, Node: IGRAPH_CHECK --- Check the return value of a function call_, Prev: igraph_errorf --- Trigger an error; printf-like version_, Up: Error handling internals
5.5.2.4 IGRAPH_CHECK -- Check the return value of a function call.
..................................................................
#define IGRAPH_CHECK(a)
*Arguments:. *
`a':
An expression, usually a function call.
Executes the expression and checks its value. If this is not
`IGRAPH_SUCCESS', it calls `IGRAPH_ERROR' (*note IGRAPH_ERROR ---
Trigger an error_::) with the value as the error code. Here is an
example usage:
IGRAPH_CHECK(vector_push_back(&v, 100));
There is only one reason to use this macro when writing `igraph'
functions. If the user installs an error handler which returns to the
auxiliary calling code (like `igraph_error_handler_ignore' (*note
igraph_error_handler_ignore --- Ignore errors_::) and
`igraph_error_handler_printignore' (*note
igraph_error_handler_printignore --- Print and ignore errors_::)), and
the `igraph' function signalling the error is called from another
`igraph' function then we need to make sure that the error is
propagated back to the auxiliary (ie. non-igraph) calling function.
This is achieved by using `IGRAPH_CHECK' on every `igraph' call which
can return an error code.
File: igraph_reference_manual.info, Node: Deallocating memory, Next: Writing igraph functions with proper error handling, Prev: Error handling internals, Up: Advanced topics
5.5.3 Deallocating memory
-------------------------
If a function runs into an error (and the program is not aborted) the
error handler should deallocate all temporary memory. This is done by
storing the address and the destroy function of all temporary objects
in a stack. The `IGRAPH_FINALLY' (*note IGRAPH_FINALLY --- Register an
object for deallocation_::) function declares an object as temporary by
placing its address in the stack. If an `igraph' function returns with
success it calls `IGRAPH_FINALLY_CLEAN()' (*note IGRAPH_FINALLY_CLEAN
--- Signal clean deallocation of objects_::) with the number of objects
to remove from the stack. If an error happens however, the error
handler should call `IGRAPH_FINALLY_FREE()' (*note IGRAPH_FINALLY_FREE
--- Deallocate all registered objects_::) to deallocate each object
added to the stack. This means that the temporary objects allocated in
the calling function (and etc.) will be freed as well.
* Menu:
* IGRAPH_FINALLY --- Register an object for deallocation.: IGRAPH_FINALLY --- Register an object for deallocation_.
* IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects.: IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects_.
* IGRAPH_FINALLY_FREE --- Deallocate all registered objects.: IGRAPH_FINALLY_FREE --- Deallocate all registered objects_.
File: igraph_reference_manual.info, Node: IGRAPH_FINALLY --- Register an object for deallocation_, Next: IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects_, Up: Deallocating memory
5.5.3.1 IGRAPH_FINALLY -- Register an object for deallocation.
..............................................................
#define IGRAPH_FINALLY(func,ptr)
*Arguments:. *
`func':
The address of the function which is normally called to destroy
the object.
`ptr':
Pointer to the object itself.
This macro places the address of an object, together with the
address of its destructor in a stack. This stack is used if an error
happens to deallocate temporarily allocated objects to prevent memory
leaks.
File: igraph_reference_manual.info, Node: IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects_, Next: IGRAPH_FINALLY_FREE --- Deallocate all registered objects_, Prev: IGRAPH_FINALLY --- Register an object for deallocation_, Up: Deallocating memory
5.5.3.2 IGRAPH_FINALLY_CLEAN -- Signal clean deallocation of objects.
.....................................................................
void IGRAPH_FINALLY_CLEAN(int num);
Removes the specified number of objects from the stack of
temporarily allocated objects. Most often this is called just before
returning from a function.
*Arguments:. *
`num':
The number of objects to remove from the bookkeeping stack.
File: igraph_reference_manual.info, Node: IGRAPH_FINALLY_FREE --- Deallocate all registered objects_, Prev: IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects_, Up: Deallocating memory
5.5.3.3 IGRAPH_FINALLY_FREE -- Deallocate all registered objects.
.................................................................
void IGRAPH_FINALLY_FREE(void);
Calls the destroy function for all objects in the stack of
temporarily allocated objects. This is usually called only from an
error handler. It is _not_ appropriate to use it instead of destroying
each unneeded object of a function, as it destroys the temporary
objects of the caller function (and so on) as well.
File: igraph_reference_manual.info, Node: Writing igraph functions with proper error handling, Next: Error handling and threads, Prev: Deallocating memory, Up: Advanced topics
5.5.4 Writing igraph functions with proper error handling
---------------------------------------------------------
There are some simple rules to keep in order to have functions behaving
well in erroneous situations. First, check the arguments of the
functions and call `IGRAPH_ERROR' (*note IGRAPH_ERROR --- Trigger an
error_::) if they are invalid. Second, call `IGRAPH_FINALLY' (*note
IGRAPH_FINALLY --- Register an object for deallocation_::) on each
dynamically allocated object and call `IGRAPH_FINALLY_CLEAN()' (*note
IGRAPH_FINALLY_CLEAN --- Signal clean deallocation of objects_::) with
the proper argument before returning. Third, use `IGRAPH_CHECK' (*note
IGRAPH_CHECK --- Check the return value of a function call_::) on all
`igraph' function calls which can generate errors.
The size of the stack used for this bookkeeping is fixed, and small.
If you want to allocate several objects, write a destroy function which
can deallocate all of these. See the `adjlist.c' file in the `igraph'
source for an example.
For some functions these mechanisms are simply not flexible enough.
These functions should define their own error handlers and restore the
error handler before they return.
File: igraph_reference_manual.info, Node: Error handling and threads, Prev: Writing igraph functions with proper error handling, Up: Advanced topics
5.5.5 Error handling and threads
--------------------------------
It is likely that the `igraph' error handling method is _not_
thread-safe, mainly because of the static global stack which is used to
store the address of the temporarily allocated objects. This issue
might be addressed in a later version of `igraph'.
File: igraph_reference_manual.info, Node: Memory [de]allocation, Next: Data structure library; vector; matrix; other data types, Prev: Error Handling, Up: Top
6 Memory (de)allocation
***********************
* Menu:
* igraph_free --- Deallocate memory that was allocated by igraph functions::
File: igraph_reference_manual.info, Node: igraph_free --- Deallocate memory that was allocated by igraph functions, Up: Memory [de]allocation
6.1 igraph_free -- Deallocate memory that was allocated by igraph functions
===========================================================================
int igraph_free(void *p);
Some igraph functions return a pointer vector (igraph_vector_ptr_t)
containing pointers to other igraph or other data types. These data
types are dynamically allocated and have to be deallocated manually, if
the user does not need them any more. This can be done by calling
igraph_free on them.
Here is a complete example on how to use `igraph_free' properly.
#include
int main(void)
{
igraph_t graph;
igraph_vector_ptr_t seps;
long int i;
igraph_famous(&graph, "tutte");
igraph_vector_ptr_init(&seps, 0);
igraph_minimum_size_separators(&graph, &seps);
for (i=0; i.
* Copying matrices::
* Accessing elements of a matrix::
* Operations on rows and columns::
* Matrix operations::
* Matrix comparisons::
* Combining matrices::
* Finding minimum and maximum: Finding minimum and maximum <1>.
* Matrix properties::
* Searching for elements: Searching for elements <1>.
* Resizing operations: Resizing operations <1>.
File: igraph_reference_manual.info, Node: About igraph_matrix_t objects, Next: Matrix constructors and destructors, Up: Matrices
7.3.1 About igraph_matrix_t objects
-----------------------------------
This type is just an interface to `igraph_vector_t'.
The `igraph_matrix_t' type usually stores n elements in O(n) space,
but not always. See the documentation of the vector type.
File: igraph_reference_manual.info, Node: Matrix constructors and destructors, Next: Initializing elements <1>, Prev: About igraph_matrix_t objects, Up: Matrices
7.3.2 Matrix constructors and destructors
-----------------------------------------
* Menu:
* igraph_matrix_init --- Initializes a matrix.: igraph_matrix_init --- Initializes a matrix_.
* igraph_matrix_copy --- Copies a matrix.: igraph_matrix_copy --- Copies a matrix_.
* igraph_matrix_destroy --- Destroys a matrix object.: igraph_matrix_destroy --- Destroys a matrix object_.
File: igraph_reference_manual.info, Node: igraph_matrix_init --- Initializes a matrix_, Next: igraph_matrix_copy --- Copies a matrix_, Up: Matrix constructors and destructors
7.3.2.1 igraph_matrix_init -- Initializes a matrix.
...................................................
int igraph_matrix_init(igraph_matrix_t *m, long int nrow, long int ncol);
Every matrix needs to be initialized before using it. This is done
by calling this function. A matrix has to be destroyed if it is not
needed any more; see `igraph_matrix_destroy()' (*note
igraph_matrix_destroy --- Destroys a matrix object_::).
*Arguments:. *
`m':
Pointer to a not yet initialized matrix object to be initialized.
`nrow':
The number of rows in the matrix.
`ncol':
The number of columns in the matrix.
*Returns:. *
`'
Error code.
Time complexity: usually O(n), n is the number of elements in the
matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_copy --- Copies a matrix_, Next: igraph_matrix_destroy --- Destroys a matrix object_, Prev: igraph_matrix_init --- Initializes a matrix_, Up: Matrix constructors and destructors
7.3.2.2 igraph_matrix_copy -- Copies a matrix.
..............................................
int igraph_matrix_copy(igraph_matrix_t *to, const igraph_matrix_t *from);
Creates a matrix object by copying from an existing matrix.
*Arguments:. *
`to':
Pointer to an uninitialized matrix object.
`from':
The initialized matrix object to copy.
*Returns:. *
`'
Error code, `IGRAPH_ENOMEM' if there isn't enough memory to
allocate the new matrix.
Time complexity: O(n), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_destroy --- Destroys a matrix object_, Prev: igraph_matrix_copy --- Copies a matrix_, Up: Matrix constructors and destructors
7.3.2.3 igraph_matrix_destroy -- Destroys a matrix object.
..........................................................
void igraph_matrix_destroy(igraph_matrix_t *m);
This function frees all the memory allocated for a matrix object.
The destroyed object needs to be reinitialized before using it again.
*Arguments:. *
`m':
The matrix to destroy.
Time complexity: operating system dependent.
File: igraph_reference_manual.info, Node: Initializing elements <1>, Next: Copying matrices, Prev: Matrix constructors and destructors, Up: Matrices
7.3.3 Initializing elements
---------------------------
* Menu:
* igraph_matrix_null --- Sets all elements in a matrix to zero.: igraph_matrix_null --- Sets all elements in a matrix to zero_.
* igraph_matrix_fill --- Fill with an element.: igraph_matrix_fill --- Fill with an element_.
File: igraph_reference_manual.info, Node: igraph_matrix_null --- Sets all elements in a matrix to zero_, Next: igraph_matrix_fill --- Fill with an element_, Up: Initializing elements <1>
7.3.3.1 igraph_matrix_null -- Sets all elements in a matrix to zero.
....................................................................
void igraph_matrix_null(igraph_matrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized matrix object.
Time complexity: O(n), n is the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_fill --- Fill with an element_, Prev: igraph_matrix_null --- Sets all elements in a matrix to zero_, Up: Initializing elements <1>
7.3.3.2 igraph_matrix_fill -- Fill with an element.
...................................................
void igraph_matrix_fill(igraph_matrix_t *m, igraph_real_t e);
Set the matrix to a constant matrix.
*Arguments:. *
`m':
The input matrix.
`e':
The element to set.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: Copying matrices, Next: Accessing elements of a matrix, Prev: Initializing elements <1>, Up: Matrices
7.3.4 Copying matrices
----------------------
* Menu:
* igraph_matrix_copy_to --- Copies a matrix to a regular C array.: igraph_matrix_copy_to --- Copies a matrix to a regular C array_.
* igraph_matrix_update --- Update from another matrix.: igraph_matrix_update --- Update from another matrix_.
* igraph_matrix_swap --- Swap two matrices.: igraph_matrix_swap --- Swap two matrices_.
File: igraph_reference_manual.info, Node: igraph_matrix_copy_to --- Copies a matrix to a regular C array_, Next: igraph_matrix_update --- Update from another matrix_, Up: Copying matrices
7.3.4.1 igraph_matrix_copy_to -- Copies a matrix to a regular C array.
......................................................................
void igraph_matrix_copy_to(const igraph_matrix_t *m, igraph_real_t *to);
The matrix is copied columnwise, as this is the format most programs
and languages use. The C array should be of sufficient size; there are
(of course) no range checks.
*Arguments:. *
`m':
Pointer to an initialized matrix object.
`to':
Pointer to a C array; the place to copy the data to.
*Returns:. *
`'
Error code.
Time complexity: O(n), n is the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_update --- Update from another matrix_, Next: igraph_matrix_swap --- Swap two matrices_, Prev: igraph_matrix_copy_to --- Copies a matrix to a regular C array_, Up: Copying matrices
7.3.4.2 igraph_matrix_update -- Update from another matrix.
...........................................................
int igraph_matrix_update(igraph_matrix_t *to,
const igraph_matrix_t *from);
This function replicates `from' in the matrix `to'. Note that `to'
must be already initialized.
*Arguments:. *
`to':
The result matrix.
`from':
The matrix to replicate; it is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_swap --- Swap two matrices_, Prev: igraph_matrix_update --- Update from another matrix_, Up: Copying matrices
7.3.4.3 igraph_matrix_swap -- Swap two matrices.
................................................
int igraph_matrix_swap(igraph_matrix_t *m1, igraph_matrix_t *m2);
The contents of the two matrices will be swapped. They must have the
same dimensions.
*Arguments:. *
`m1':
The first matrix.
`m2':
The second matrix.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the matrices.
File: igraph_reference_manual.info, Node: Accessing elements of a matrix, Next: Operations on rows and columns, Prev: Copying matrices, Up: Matrices
7.3.5 Accessing elements of a matrix
------------------------------------
* Menu:
* MATRIX --- Accessing an element of a matrix.: MATRIX --- Accessing an element of a matrix_.
* igraph_matrix_e --- Extract an element from a matrix.: igraph_matrix_e --- Extract an element from a matrix_.
* igraph_matrix_e_ptr --- Pointer to an element of a matrix.: igraph_matrix_e_ptr --- Pointer to an element of a matrix_.
* igraph_matrix_set --- Set an element.: igraph_matrix_set --- Set an element_.
File: igraph_reference_manual.info, Node: MATRIX --- Accessing an element of a matrix_, Next: igraph_matrix_e --- Extract an element from a matrix_, Up: Accessing elements of a matrix
7.3.5.1 MATRIX -- Accessing an element of a matrix.
...................................................
#define MATRIX(m,i,j)
Note that there are no range checks right now. This functionality
might be redefined as a proper function later.
*Arguments:. *
`m':
The matrix object.
`i':
The index of the row, starting with zero.
`j':
The index of the column, starting with zero.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_e --- Extract an element from a matrix_, Next: igraph_matrix_e_ptr --- Pointer to an element of a matrix_, Prev: MATRIX --- Accessing an element of a matrix_, Up: Accessing elements of a matrix
7.3.5.2 igraph_matrix_e -- Extract an element from a matrix.
............................................................
igraph_real_t igraph_matrix_e(const igraph_matrix_t *m,
long int row, long int col);
Use this if you need a function for some reason and cannot use the
`MATRIX' (*note MATRIX --- Accessing an element of a matrix_::) macro.
Note that no range checking is performed.
*Arguments:. *
`m':
The input matrix.
`row':
The row index.
`col':
The column index.
*Returns:. *
`'
The element in the given row and column.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_e_ptr --- Pointer to an element of a matrix_, Next: igraph_matrix_set --- Set an element_, Prev: igraph_matrix_e --- Extract an element from a matrix_, Up: Accessing elements of a matrix
7.3.5.3 igraph_matrix_e_ptr -- Pointer to an element of a matrix.
.................................................................
igraph_real_t* igraph_matrix_e_ptr(const igraph_matrix_t *m,
long int row, long int col);
The function returns a pointer to an element. No range checking is
performed.
*Arguments:. *
`m':
The input matrix.
`row':
The row index.
`col':
The column index.
*Returns:. *
`'
Pointer to the element in the given row and column.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_set --- Set an element_, Prev: igraph_matrix_e_ptr --- Pointer to an element of a matrix_, Up: Accessing elements of a matrix
7.3.5.4 igraph_matrix_set -- Set an element.
............................................
void igraph_matrix_set(igraph_matrix_t* m, long int row, long int col,
igraph_real_t value);
Set an element of a matrix. No range checking is performed.
*Arguments:. *
`m':
The input matrix.
`row':
The row index.
`col':
The column index.
`value':
The new value of the element.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Operations on rows and columns, Next: Matrix operations, Prev: Accessing elements of a matrix, Up: Matrices
7.3.6 Operations on rows and columns
------------------------------------
* Menu:
* igraph_matrix_get_row --- Extract a row.: igraph_matrix_get_row --- Extract a row_.
* igraph_matrix_get_col --- Select a column.: igraph_matrix_get_col --- Select a column_.
* igraph_matrix_set_row --- Set a row from a vector.: igraph_matrix_set_row --- Set a row from a vector_.
* igraph_matrix_set_col --- Set a column from a vector.: igraph_matrix_set_col --- Set a column from a vector_.
* igraph_matrix_swap_rows --- Swap two rows.: igraph_matrix_swap_rows --- Swap two rows_.
* igraph_matrix_swap_cols --- Swap two columns.: igraph_matrix_swap_cols --- Swap two columns_.
* igraph_matrix_select_rows --- Select some rows of a matrix.: igraph_matrix_select_rows --- Select some rows of a matrix_.
* igraph_matrix_select_cols --- Select some columns of a matrix.: igraph_matrix_select_cols --- Select some columns of a matrix_.
* igraph_matrix_select_rows_cols --- Select some rows and columns of a matrix.: igraph_matrix_select_rows_cols --- Select some rows and columns of a matrix_.
File: igraph_reference_manual.info, Node: igraph_matrix_get_row --- Extract a row_, Next: igraph_matrix_get_col --- Select a column_, Up: Operations on rows and columns
7.3.6.1 igraph_matrix_get_row -- Extract a row.
...............................................
int igraph_matrix_get_row(const igraph_matrix_t *m,
igraph_vector_t *res, long int index);
Extract a row from a matrix and return it as a vector.
*Arguments:. *
`m':
The input matrix.
`res':
Pointer to an initialized vector; it will be resized if needed.
`index':
The index of the row to select.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of columns in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_get_col --- Select a column_, Next: igraph_matrix_set_row --- Set a row from a vector_, Prev: igraph_matrix_get_row --- Extract a row_, Up: Operations on rows and columns
7.3.6.2 igraph_matrix_get_col -- Select a column.
.................................................
int igraph_matrix_get_col(const igraph_matrix_t *m,
igraph_vector_t *res,
long int index);
Extract a column of a matrix and return it as a vector.
*Arguments:. *
`m':
The input matrix.
`res':
The result will we stored in this vector. It should be initialized
and will be resized as needed.
`index':
The index of the column to select.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of rows in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_set_row --- Set a row from a vector_, Next: igraph_matrix_set_col --- Set a column from a vector_, Prev: igraph_matrix_get_col --- Select a column_, Up: Operations on rows and columns
7.3.6.3 igraph_matrix_set_row -- Set a row from a vector.
.........................................................
int igraph_matrix_set_row(igraph_matrix_t *m,
const igraph_vector_t *v, long int index);
Sets the elements of a row with the given vector. This has the
effect of setting row `index' to have the elements in the vector `v'.
The length of the vector and the number of columns in the matrix must
match, otherwise an error is triggered.
*Arguments:. *
`m':
The input matrix.
`v':
The vector containing the new elements of the row.
`index':
Index of the row to set.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of columns in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_set_col --- Set a column from a vector_, Next: igraph_matrix_swap_rows --- Swap two rows_, Prev: igraph_matrix_set_row --- Set a row from a vector_, Up: Operations on rows and columns
7.3.6.4 igraph_matrix_set_col -- Set a column from a vector.
............................................................
int igraph_matrix_set_col(igraph_matrix_t *m,
const igraph_vector_t *v, long int index);
Sets the elements of a column with the given vector. In effect,
column `index' will be set with elements from the vector `v'. The
length of the vector and the number of rows in the matrix must match,
otherwise an error is triggered.
*Arguments:. *
`m':
The input matrix.
`v':
The vector containing the new elements of the column.
`index':
Index of the column to set.
*Returns:. *
`'
Error code.
Time complexity: O(m), the number of rows in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_swap_rows --- Swap two rows_, Next: igraph_matrix_swap_cols --- Swap two columns_, Prev: igraph_matrix_set_col --- Set a column from a vector_, Up: Operations on rows and columns
7.3.6.5 igraph_matrix_swap_rows -- Swap two rows.
.................................................
int igraph_matrix_swap_rows(igraph_matrix_t *m,
long int i, long int j);
Swap two rows in the matrix.
*Arguments:. *
`m':
The input matrix.
`i':
The index of the first row.
`j':
The index of the second row.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of columns.
File: igraph_reference_manual.info, Node: igraph_matrix_swap_cols --- Swap two columns_, Next: igraph_matrix_select_rows --- Select some rows of a matrix_, Prev: igraph_matrix_swap_rows --- Swap two rows_, Up: Operations on rows and columns
7.3.6.6 igraph_matrix_swap_cols -- Swap two columns.
....................................................
int igraph_matrix_swap_cols(igraph_matrix_t *m,
long int i, long int j);
Swap two columns in the matrix.
*Arguments:. *
`m':
The input matrix.
`i':
The index of the first column.
`j':
The index of the second column.
*Returns:. *
`'
Error code.
Time complexity: O(m), the number of rows.
File: igraph_reference_manual.info, Node: igraph_matrix_select_rows --- Select some rows of a matrix_, Next: igraph_matrix_select_cols --- Select some columns of a matrix_, Prev: igraph_matrix_swap_cols --- Swap two columns_, Up: Operations on rows and columns
7.3.6.7 igraph_matrix_select_rows -- Select some rows of a matrix.
..................................................................
int igraph_matrix_select_rows(const igraph_matrix_t *m,
igraph_matrix_t *res,
const igraph_vector_t *rows);
This function selects some rows of a matrix and returns them in a
new matrix. The result matrix should be initialized before calling the
function.
*Arguments:. *
`m':
The input matrix.
`res':
The result matrix. It should be initialized and will be resized as
needed.
`rows':
Vector; it contains the row indices (starting with zero) to
extract. Note that no range checking is performed.
*Returns:. *
`'
Error code.
Time complexity: O(nm), n is the number of rows, m the number of
columns of the result matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_select_cols --- Select some columns of a matrix_, Next: igraph_matrix_select_rows_cols --- Select some rows and columns of a matrix_, Prev: igraph_matrix_select_rows --- Select some rows of a matrix_, Up: Operations on rows and columns
7.3.6.8 igraph_matrix_select_cols -- Select some columns of a matrix.
.....................................................................
int igraph_matrix_select_cols(const igraph_matrix_t *m,
igraph_matrix_t *res,
const igraph_vector_t *cols);
This function selects some columns of a matrix and returns them in a
new matrix. The result matrix should be initialized before calling the
function.
*Arguments:. *
`m':
The input matrix.
`res':
The result matrix. It should be initialized and will be resized as
needed.
`cols':
Vector; it contains the column indices (starting with zero) to
extract. Note that no range checking is performed.
*Returns:. *
`'
Error code.
Time complexity: O(nm), n is the number of rows, m the number of
columns of the result matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_select_rows_cols --- Select some rows and columns of a matrix_, Prev: igraph_matrix_select_cols --- Select some columns of a matrix_, Up: Operations on rows and columns
7.3.6.9 igraph_matrix_select_rows_cols -- Select some rows and columns of a matrix.
...................................................................................
int igraph_matrix_select_rows_cols(const igraph_matrix_t *m,
igraph_matrix_t *res,
const igraph_vector_t *rows,
const igraph_vector_t *cols);
This function selects some rows and columns of a matrix and returns
them in a new matrix. The result matrix should be initialized before
calling the function.
*Arguments:. *
`m':
The input matrix.
`res':
The result matrix. It should be initialized and will be resized as
needed.
`rows':
Vector; it contains the row indices (starting with zero) to
extract. Note that no range checking is performed.
`cols':
Vector; it contains the column indices (starting with zero) to
extract. Note that no range checking is performed.
*Returns:. *
`'
Error code.
Time complexity: O(nm), n is the number of rows, m the number of
columns of the result matrix.
File: igraph_reference_manual.info, Node: Matrix operations, Next: Matrix comparisons, Prev: Operations on rows and columns, Up: Matrices
7.3.7 Matrix operations
-----------------------
* Menu:
* igraph_matrix_add_constant --- Add a constant to every element.: igraph_matrix_add_constant --- Add a constant to every element_.
* igraph_matrix_scale --- Multiplies each element of the matrix by a constant.: igraph_matrix_scale --- Multiplies each element of the matrix by a constant_.
* igraph_matrix_add --- Add two matrices.: igraph_matrix_add --- Add two matrices_.
* igraph_matrix_sub --- Difference of two matrices.: igraph_matrix_sub --- Difference of two matrices_.
* igraph_matrix_mul_elements --- Elementwise multiplication.: igraph_matrix_mul_elements --- Elementwise multiplication_.
* igraph_matrix_div_elements --- Elementwise division.: igraph_matrix_div_elements --- Elementwise division_.
* igraph_matrix_sum --- Sum of elements.: igraph_matrix_sum --- Sum of elements_.
* igraph_matrix_prod --- Product of the elements.: igraph_matrix_prod --- Product of the elements_.
* igraph_matrix_rowsum --- Rowwise sum.: igraph_matrix_rowsum --- Rowwise sum_.
* igraph_matrix_colsum --- Columnwise sum.: igraph_matrix_colsum --- Columnwise sum_.
* igraph_matrix_transpose --- Transpose a matrix.: igraph_matrix_transpose --- Transpose a matrix_.
File: igraph_reference_manual.info, Node: igraph_matrix_add_constant --- Add a constant to every element_, Next: igraph_matrix_scale --- Multiplies each element of the matrix by a constant_, Up: Matrix operations
7.3.7.1 igraph_matrix_add_constant -- Add a constant to every element.
......................................................................
void igraph_matrix_add_constant(igraph_matrix_t *m, igraph_real_t plus);
*Arguments:. *
`m':
The input matrix.
`plud':
The constant to add.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_scale --- Multiplies each element of the matrix by a constant_, Next: igraph_matrix_add --- Add two matrices_, Prev: igraph_matrix_add_constant --- Add a constant to every element_, Up: Matrix operations
7.3.7.2 igraph_matrix_scale -- Multiplies each element of the matrix by a constant.
...................................................................................
void igraph_matrix_scale(igraph_matrix_t *m, igraph_real_t by);
*Arguments:. *
`m':
The matrix.
`by':
The constant.
Added in version 0.2.
Time complexity: O(n), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_add --- Add two matrices_, Next: igraph_matrix_sub --- Difference of two matrices_, Prev: igraph_matrix_scale --- Multiplies each element of the matrix by a constant_, Up: Matrix operations
7.3.7.3 igraph_matrix_add -- Add two matrices.
..............................................
int igraph_matrix_add(igraph_matrix_t *m1,
const igraph_matrix_t *m2);
Add `m2' to `m1', and store the result in `m1'. The dimensions of the
matrices must match.
*Arguments:. *
`m1':
The first matrix; the result will be stored here.
`m2':
The second matrix; it is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_sub --- Difference of two matrices_, Next: igraph_matrix_mul_elements --- Elementwise multiplication_, Prev: igraph_matrix_add --- Add two matrices_, Up: Matrix operations
7.3.7.4 igraph_matrix_sub -- Difference of two matrices.
........................................................
int igraph_matrix_sub(igraph_matrix_t *m1,
const igraph_matrix_t *m2);
Subtract `m2' from `m1' and store the result in `m1'. The
dimensions of the two matrices must match.
*Arguments:. *
`m1':
The first matrix; the result is stored here.
`m2':
The second matrix; it is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_mul_elements --- Elementwise multiplication_, Next: igraph_matrix_div_elements --- Elementwise division_, Prev: igraph_matrix_sub --- Difference of two matrices_, Up: Matrix operations
7.3.7.5 igraph_matrix_mul_elements -- Elementwise multiplication.
.................................................................
int igraph_matrix_mul_elements(igraph_matrix_t *m1,
const igraph_matrix_t *m2);
Multiply `m1' by `m2' elementwise and store the result in `m1'. The
dimensions of the two matrices must match.
*Arguments:. *
`m1':
The first matrix; the result is stored here.
`m2':
The second matrix; it is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_div_elements --- Elementwise division_, Next: igraph_matrix_sum --- Sum of elements_, Prev: igraph_matrix_mul_elements --- Elementwise multiplication_, Up: Matrix operations
7.3.7.6 igraph_matrix_div_elements -- Elementwise division.
...........................................................
int igraph_matrix_div_elements(igraph_matrix_t *m1,
const igraph_matrix_t *m2);
Divide `m1' by `m2' elementwise and store the result in `m1'. The
dimensions of the two matrices must match.
*Arguments:. *
`m1':
The dividend. The result is store here.
`m2':
The divisor. It is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_sum --- Sum of elements_, Next: igraph_matrix_prod --- Product of the elements_, Prev: igraph_matrix_div_elements --- Elementwise division_, Up: Matrix operations
7.3.7.7 igraph_matrix_sum -- Sum of elements.
.............................................
igraph_real_t igraph_matrix_sum(const igraph_matrix_t *m);
Returns the sum of the elements of a matrix.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
The sum of the elements.
Time complexity: O(mn), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_prod --- Product of the elements_, Next: igraph_matrix_rowsum --- Rowwise sum_, Prev: igraph_matrix_sum --- Sum of elements_, Up: Matrix operations
7.3.7.8 igraph_matrix_prod -- Product of the elements.
......................................................
igraph_real_t igraph_matrix_prod(const igraph_matrix_t *m);
Note this function can result in overflow easily, even for not too
big matrices.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
The product of the elements.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_rowsum --- Rowwise sum_, Next: igraph_matrix_colsum --- Columnwise sum_, Prev: igraph_matrix_prod --- Product of the elements_, Up: Matrix operations
7.3.7.9 igraph_matrix_rowsum -- Rowwise sum.
............................................
int igraph_matrix_rowsum(const igraph_matrix_t *m,
igraph_vector_t *res);
Calculate the sum of the elements in each row.
*Arguments:. *
`m':
The input matrix.
`res':
Pointer to an initialized vector; the result is stored here. It
will be resized if necessary.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_colsum --- Columnwise sum_, Next: igraph_matrix_transpose --- Transpose a matrix_, Prev: igraph_matrix_rowsum --- Rowwise sum_, Up: Matrix operations
7.3.7.10 igraph_matrix_colsum -- Columnwise sum.
................................................
int igraph_matrix_colsum(const igraph_matrix_t *m,
igraph_vector_t *res);
Calculate the sum of the elements in each column.
*Arguments:. *
`m':
The input matrix.
`res':
Pointer to an initialized vector; the result is stored here. It
will be resized if necessary.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_transpose --- Transpose a matrix_, Prev: igraph_matrix_colsum --- Columnwise sum_, Up: Matrix operations
7.3.7.11 igraph_matrix_transpose -- Transpose a matrix.
.......................................................
int igraph_matrix_transpose(igraph_matrix_t *m);
Calculate the transpose of a matrix. Note that the function
reallocates the memory used for the matrix.
*Arguments:. *
`m':
The input (and output) matrix.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: Matrix comparisons, Next: Combining matrices, Prev: Matrix operations, Up: Matrices
7.3.8 Matrix comparisons
------------------------
* Menu:
* igraph_matrix_all_e --- Are all elements equal?::
* igraph_matrix_all_l --- Are all elements less?::
* igraph_matrix_all_g --- Are all elements greater?::
* igraph_matrix_all_le --- Are all elements less or equal?::
* igraph_matrix_all_ge --- Are all elements greater or equal?::
File: igraph_reference_manual.info, Node: igraph_matrix_all_e --- Are all elements equal?, Next: igraph_matrix_all_l --- Are all elements less?, Up: Matrix comparisons
7.3.8.1 igraph_matrix_all_e -- Are all elements equal?
......................................................
igraph_bool_t igraph_matrix_all_e(const igraph_matrix_t *lhs,
const igraph_matrix_t *rhs);
*Arguments:. *
`lhs':
The first matrix.
`rhs':
The second matrix.
*Returns:. *
`'
Positive integer (=true) if the elements in the `lhs' are all
equal to the corresponding elements in `rhs'. Returns `0' (=false)
if the dimensions of the matrices don't match.
Time complexity: O(nm), the size of the matrices.
File: igraph_reference_manual.info, Node: igraph_matrix_all_l --- Are all elements less?, Next: igraph_matrix_all_g --- Are all elements greater?, Prev: igraph_matrix_all_e --- Are all elements equal?, Up: Matrix comparisons
7.3.8.2 igraph_matrix_all_l -- Are all elements less?
.....................................................
igraph_bool_t igraph_matrix_all_l(const igraph_matrix_t *lhs,
const igraph_matrix_t *rhs);
*Arguments:. *
`lhs':
The first matrix.
`rhs':
The second matrix.
*Returns:. *
`'
Positive integer (=true) if the elements in the `lhs' are all less
than the corresponding elements in `rhs'. Returns `0' (=false) if
the dimensions of the matrices don't match.
Time complexity: O(nm), the size of the matrices.
File: igraph_reference_manual.info, Node: igraph_matrix_all_g --- Are all elements greater?, Next: igraph_matrix_all_le --- Are all elements less or equal?, Prev: igraph_matrix_all_l --- Are all elements less?, Up: Matrix comparisons
7.3.8.3 igraph_matrix_all_g -- Are all elements greater?
........................................................
igraph_bool_t igraph_matrix_all_g(const igraph_matrix_t *lhs,
const igraph_matrix_t *rhs);
*Arguments:. *
`lhs':
The first matrix.
`rhs':
The second matrix.
*Returns:. *
`'
Positive integer (=true) if the elements in the `lhs' are all
greater than the corresponding elements in `rhs'. Returns `0'
(=false) if the dimensions of the matrices don't match.
Time complexity: O(nm), the size of the matrices.
File: igraph_reference_manual.info, Node: igraph_matrix_all_le --- Are all elements less or equal?, Next: igraph_matrix_all_ge --- Are all elements greater or equal?, Prev: igraph_matrix_all_g --- Are all elements greater?, Up: Matrix comparisons
7.3.8.4 igraph_matrix_all_le -- Are all elements less or equal?
...............................................................
igraph_bool_t
igraph_matrix_all_le(const igraph_matrix_t *lhs,
const igraph_matrix_t *rhs);
*Arguments:. *
`lhs':
The first matrix.
`rhs':
The second matrix.
*Returns:. *
`'
Positive integer (=true) if the elements in the `lhs' are all less
than or equal to the corresponding elements in `rhs'. Returns `0'
(=false) if the dimensions of the matrices don't match.
Time complexity: O(nm), the size of the matrices.
File: igraph_reference_manual.info, Node: igraph_matrix_all_ge --- Are all elements greater or equal?, Prev: igraph_matrix_all_le --- Are all elements less or equal?, Up: Matrix comparisons
7.3.8.5 igraph_matrix_all_ge -- Are all elements greater or equal?
..................................................................
igraph_bool_t
igraph_matrix_all_ge(const igraph_matrix_t *lhs,
const igraph_matrix_t *rhs);
*Arguments:. *
`lhs':
The first matrix.
`rhs':
The second matrix.
*Returns:. *
`'
Positive integer (=true) if the elements in the `lhs' are all
greater than or equal to the corresponding elements in `rhs'.
Returns `0' (=false) if the dimensions of the matrices don't match.
Time complexity: O(nm), the size of the matrices.
File: igraph_reference_manual.info, Node: Combining matrices, Next: Finding minimum and maximum <1>, Prev: Matrix comparisons, Up: Matrices
7.3.9 Combining matrices
------------------------
* Menu:
* igraph_matrix_rbind --- Combine two matrices rowwise.: igraph_matrix_rbind --- Combine two matrices rowwise_.
* igraph_matrix_cbind --- Combine matrices columnwise.: igraph_matrix_cbind --- Combine matrices columnwise_.
File: igraph_reference_manual.info, Node: igraph_matrix_rbind --- Combine two matrices rowwise_, Next: igraph_matrix_cbind --- Combine matrices columnwise_, Up: Combining matrices
7.3.9.1 igraph_matrix_rbind -- Combine two matrices rowwise.
............................................................
int igraph_matrix_rbind(igraph_matrix_t *to,
const igraph_matrix_t *from);
This function places the rows of `from' below the rows of `to' and
stores the result in `to'. The number of columns in the two matrices
must match.
*Arguments:. *
`to':
The upper matrix; the result is also stored here.
`from':
The lower matrix. It is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the newly created
matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_cbind --- Combine matrices columnwise_, Prev: igraph_matrix_rbind --- Combine two matrices rowwise_, Up: Combining matrices
7.3.9.2 igraph_matrix_cbind -- Combine matrices columnwise.
...........................................................
int igraph_matrix_cbind(igraph_matrix_t *to,
const igraph_matrix_t *from);
This function places the columns of `from' on the right of `to', and
stores the result in `to'.
*Arguments:. *
`to':
The left matrix; the result is stored here too.
`from':
The right matrix. It is left unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements on the new matrix.
File: igraph_reference_manual.info, Node: Finding minimum and maximum <1>, Next: Matrix properties, Prev: Combining matrices, Up: Matrices
7.3.10 Finding minimum and maximum
----------------------------------
* Menu:
* igraph_matrix_min --- Minimum element.: igraph_matrix_min --- Minimum element_.
* igraph_matrix_max --- Returns the maximal element of a matrix.: igraph_matrix_max --- Returns the maximal element of a matrix_.
* igraph_matrix_which_min --- Indices of the minimum.: igraph_matrix_which_min --- Indices of the minimum_.
* igraph_matrix_which_max --- Indices of the maximum.: igraph_matrix_which_max --- Indices of the maximum_.
* igraph_matrix_minmax --- Minimum and maximum::
* igraph_matrix_which_minmax --- Indices of the minimum and maximum::
File: igraph_reference_manual.info, Node: igraph_matrix_min --- Minimum element_, Next: igraph_matrix_max --- Returns the maximal element of a matrix_, Up: Finding minimum and maximum <1>
7.3.10.1 igraph_matrix_min -- Minimum element.
..............................................
igraph_real_t igraph_matrix_min(const igraph_matrix_t *m);
Returns the smallest element of a non-empty matrix.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
The smallest element.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_max --- Returns the maximal element of a matrix_, Next: igraph_matrix_which_min --- Indices of the minimum_, Prev: igraph_matrix_min --- Minimum element_, Up: Finding minimum and maximum <1>
7.3.10.2 igraph_matrix_max -- Returns the maximal element of a matrix.
......................................................................
igraph_real_t igraph_matrix_max(const igraph_matrix_t *m);
*Arguments:. *
`m':
The matrix object.
*Returns:. *
`'
The maximum element. For empty matrix the returned value is
undefined.
Added in version 0.2.
Time complexity: O(n), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_which_min --- Indices of the minimum_, Next: igraph_matrix_which_max --- Indices of the maximum_, Prev: igraph_matrix_max --- Returns the maximal element of a matrix_, Up: Finding minimum and maximum <1>
7.3.10.3 igraph_matrix_which_min -- Indices of the minimum.
...........................................................
int igraph_matrix_which_min(const igraph_matrix_t *m,
long int *i, long int *j);
Gives the indices of the (first) smallest element in a non-empty
matrix.
*Arguments:. *
`m':
The matrix.
`i':
Pointer to a `long int'. The row index of the minimum is stored
here.
`j':
Pointer to a `long int'. The column index of the minimum is stored
here.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_which_max --- Indices of the maximum_, Next: igraph_matrix_minmax --- Minimum and maximum, Prev: igraph_matrix_which_min --- Indices of the minimum_, Up: Finding minimum and maximum <1>
7.3.10.4 igraph_matrix_which_max -- Indices of the maximum.
...........................................................
int igraph_matrix_which_max(const igraph_matrix_t *m,
long int *i, long int *j);
Gives the indices of the (first) largest element in a non-empty
matrix.
*Arguments:. *
`m':
The matrix.
`i':
Pointer to a `long int'. The row index of the maximum is stored
here.
`j':
Pointer to a `long int'. The column index of the maximum is stored
here.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_minmax --- Minimum and maximum, Next: igraph_matrix_which_minmax --- Indices of the minimum and maximum, Prev: igraph_matrix_which_max --- Indices of the maximum_, Up: Finding minimum and maximum <1>
7.3.10.5 igraph_matrix_minmax -- Minimum and maximum
....................................................
int igraph_matrix_minmax(const igraph_matrix_t *m,
igraph_real_t *min, igraph_real_t *max);
The maximum and minimum elements of a non-empty matrix.
*Arguments:. *
`m':
The input matrix.
`min':
Pointer to a base type. The minimum is stored here.
`max':
Pointer to a base type. The maximum is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_which_minmax --- Indices of the minimum and maximum, Prev: igraph_matrix_minmax --- Minimum and maximum, Up: Finding minimum and maximum <1>
7.3.10.6 igraph_matrix_which_minmax -- Indices of the minimum and maximum
.........................................................................
int igraph_matrix_which_minmax(const igraph_matrix_t *m,
long int *imin, long int *jmin,
long int *imax, long int *jmax);
Find the positions of the smallest and largest elements of a
non-empty matrix.
*Arguments:. *
`m':
The input matrix.
`imin':
Pointer to a `long int', the row index of the minimum is stored
here.
`jmin':
Pointer to a `long int', the column index of the minimum is stored
here.
`imax':
Pointer to a `long int', the row index of the maximum is stored
here.
`jmax':
Pointer to a `long int', the column index of the maximum is stored
here.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: Matrix properties, Next: Searching for elements <1>, Prev: Finding minimum and maximum <1>, Up: Matrices
7.3.11 Matrix properties
------------------------
* Menu:
* igraph_matrix_empty --- Check for an empty matrix.: igraph_matrix_empty --- Check for an empty matrix_.
* igraph_matrix_isnull --- Check for a null matrix.: igraph_matrix_isnull --- Check for a null matrix_.
* igraph_matrix_size --- The number of elements in a matrix.: igraph_matrix_size --- The number of elements in a matrix_.
* igraph_matrix_capacity --- Returns the number of elements allocated for a matrix.: igraph_matrix_capacity --- Returns the number of elements allocated for a matrix_.
* igraph_matrix_nrow --- The number of rows in a matrix.: igraph_matrix_nrow --- The number of rows in a matrix_.
* igraph_matrix_ncol --- The number of columns in a matrix.: igraph_matrix_ncol --- The number of columns in a matrix_.
* igraph_matrix_is_symmetric --- Check for symmetric matrix.: igraph_matrix_is_symmetric --- Check for symmetric matrix_.
* igraph_matrix_maxdifference --- Maximum absolute difference between two matrices.: igraph_matrix_maxdifference --- Maximum absolute difference between two matrices_.
File: igraph_reference_manual.info, Node: igraph_matrix_empty --- Check for an empty matrix_, Next: igraph_matrix_isnull --- Check for a null matrix_, Up: Matrix properties
7.3.11.1 igraph_matrix_empty -- Check for an empty matrix.
..........................................................
igraph_bool_t igraph_matrix_empty(const igraph_matrix_t *m);
It is possible to have a matrix with zero rows or zero columns, or
even both. This functions checks for these.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
Boolean, `TRUE' if the matrix contains zero elements, and `FALSE'
otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_isnull --- Check for a null matrix_, Next: igraph_matrix_size --- The number of elements in a matrix_, Prev: igraph_matrix_empty --- Check for an empty matrix_, Up: Matrix properties
7.3.11.2 igraph_matrix_isnull -- Check for a null matrix.
.........................................................
igraph_bool_t igraph_matrix_isnull(const igraph_matrix_t *m);
Checks whether all elements are zero.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
Boolean, `TRUE' is `m' contains only zeros and `FALSE' otherwise.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_size --- The number of elements in a matrix_, Next: igraph_matrix_capacity --- Returns the number of elements allocated for a matrix_, Prev: igraph_matrix_isnull --- Check for a null matrix_, Up: Matrix properties
7.3.11.3 igraph_matrix_size -- The number of elements in a matrix.
..................................................................
long int igraph_matrix_size(const igraph_matrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized matrix object.
*Returns:. *
`'
The size of the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_capacity --- Returns the number of elements allocated for a matrix_, Next: igraph_matrix_nrow --- The number of rows in a matrix_, Prev: igraph_matrix_size --- The number of elements in a matrix_, Up: Matrix properties
7.3.11.4 igraph_matrix_capacity -- Returns the number of elements allocated for a matrix.
.........................................................................................
long int igraph_matrix_capacity(const igraph_matrix_t *m);
Note that this might be different from the size of the matrix (as
queried by `igraph_matrix_size()' (*note igraph_matrix_size --- The
number of elements in a matrix_::), and specifies how many elements the
matrix can hold, without reallocation.
*Arguments:. *
`v':
Pointer to the (previously initialized) matrix object to query.
*Returns:. *
`'
The allocated capacity.
*See also:. *
`'
`igraph_matrix_size()' (*note igraph_matrix_size --- The number of
elements in a matrix_::), `igraph_matrix_nrow()' (*note
igraph_matrix_nrow --- The number of rows in a matrix_::),
`igraph_matrix_ncol()' (*note igraph_matrix_ncol --- The number of
columns in a matrix_::).
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_nrow --- The number of rows in a matrix_, Next: igraph_matrix_ncol --- The number of columns in a matrix_, Prev: igraph_matrix_capacity --- Returns the number of elements allocated for a matrix_, Up: Matrix properties
7.3.11.5 igraph_matrix_nrow -- The number of rows in a matrix.
..............................................................
long int igraph_matrix_nrow(const igraph_matrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized matrix object.
*Returns:. *
`'
The number of rows in the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_ncol --- The number of columns in a matrix_, Next: igraph_matrix_is_symmetric --- Check for symmetric matrix_, Prev: igraph_matrix_nrow --- The number of rows in a matrix_, Up: Matrix properties
7.3.11.6 igraph_matrix_ncol -- The number of columns in a matrix.
.................................................................
long int igraph_matrix_ncol(const igraph_matrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized matrix object.
*Returns:. *
`'
The number of columns in the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_matrix_is_symmetric --- Check for symmetric matrix_, Next: igraph_matrix_maxdifference --- Maximum absolute difference between two matrices_, Prev: igraph_matrix_ncol --- The number of columns in a matrix_, Up: Matrix properties
7.3.11.7 igraph_matrix_is_symmetric -- Check for symmetric matrix.
..................................................................
igraph_bool_t igraph_matrix_is_symmetric(const igraph_matrix_t *m);
A non-square matrix is not symmetric by definition.
*Arguments:. *
`m':
The input matrix.
*Returns:. *
`'
Boolean, `TRUE' if the matrix is square and symmetric, `FALSE'
otherwise.
Time complexity: O(mn), the number of elements. O(1) for non-square
matrices.
File: igraph_reference_manual.info, Node: igraph_matrix_maxdifference --- Maximum absolute difference between two matrices_, Prev: igraph_matrix_is_symmetric --- Check for symmetric matrix_, Up: Matrix properties
7.3.11.8 igraph_matrix_maxdifference -- Maximum absolute difference between two matrices.
.........................................................................................
igraph_real_t igraph_matrix_maxdifference(const igraph_matrix_t *m1,
const igraph_matrix_t *m2);
Calculate the maximum absolute difference of two matrices. Both
matrices must be non-empty. If their dimensions differ then a warning
is given and the comparison is performed by vectors columnwise from
both matrices. The remaining elements in the larger vector are ignored.
*Arguments:. *
`m1':
The first matrix.
`m2':
The second matrix.
*Returns:. *
`'
The element with the largest absolute value in `m1' - `m2'.
Time complexity: O(mn), the elements in the smaller matrix.
File: igraph_reference_manual.info, Node: Searching for elements <1>, Next: Resizing operations <1>, Prev: Matrix properties, Up: Matrices
7.3.12 Searching for elements
-----------------------------
* Menu:
* igraph_matrix_contains --- Search for an element.: igraph_matrix_contains --- Search for an element_.
* igraph_matrix_search --- Search from a given position.: igraph_matrix_search --- Search from a given position_.
File: igraph_reference_manual.info, Node: igraph_matrix_contains --- Search for an element_, Next: igraph_matrix_search --- Search from a given position_, Up: Searching for elements <1>
7.3.12.1 igraph_matrix_contains -- Search for an element.
.........................................................
igraph_bool_t igraph_matrix_contains(const igraph_matrix_t *m,
igraph_real_t e);
Search for the given element in the matrix.
*Arguments:. *
`m':
The input matrix.
`e':
The element to search for.
*Returns:. *
`'
Boolean, `TRUE' if the matrix contains `e', `FALSE' otherwise.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: igraph_matrix_search --- Search from a given position_, Prev: igraph_matrix_contains --- Search for an element_, Up: Searching for elements <1>
7.3.12.2 igraph_matrix_search -- Search from a given position.
..............................................................
igraph_bool_t igraph_matrix_search(const igraph_matrix_t *m,
long int from, igraph_real_t what,
long int *pos,
long int *row, long int *col);
Search for an element in a matrix and start the search from the
given position. The search is performed columnwise.
*Arguments:. *
`m':
The input matrix.
`from':
The position to search from, the positions are enumerated
columnwise.
`what':
The element to search for.
`pos':
Pointer to a `long int'. If the element is found, then this is set
to the position of its first appearance.
`row':
Pointer to a `long int'. If the element is found, then this is set
to its row index.
`col':
Pointer to a `long int'. If the element is found, then this is set
to its column index.
*Returns:. *
`'
Boolean, `TRUE' if the element is found, `FALSE' otherwise.
Time complexity: O(mn), the number of elements.
File: igraph_reference_manual.info, Node: Resizing operations <1>, Prev: Searching for elements <1>, Up: Matrices
7.3.13 Resizing operations
--------------------------
* Menu:
* igraph_matrix_resize --- Resizes a matrix.: igraph_matrix_resize --- Resizes a matrix_.
* igraph_matrix_resize_min --- Deallocates unused memory for a matrix.: igraph_matrix_resize_min --- Deallocates unused memory for a matrix_.
* igraph_matrix_add_rows --- Adds rows to a matrix.: igraph_matrix_add_rows --- Adds rows to a matrix_.
* igraph_matrix_add_cols --- Adds columns to a matrix.: igraph_matrix_add_cols --- Adds columns to a matrix_.
* igraph_matrix_remove_row --- Remove a row.: igraph_matrix_remove_row --- Remove a row_.
* igraph_matrix_remove_col --- Removes a column from a matrix.: igraph_matrix_remove_col --- Removes a column from a matrix_.
File: igraph_reference_manual.info, Node: igraph_matrix_resize --- Resizes a matrix_, Next: igraph_matrix_resize_min --- Deallocates unused memory for a matrix_, Up: Resizing operations <1>
7.3.13.1 igraph_matrix_resize -- Resizes a matrix.
..................................................
int igraph_matrix_resize(igraph_matrix_t *m, long int nrow, long int ncol);
This function resizes a matrix by adding more elements to it. The
matrix contains arbitrary data after resizing it. That is, after
calling this function you cannot expect that element (i,j) in the
matrix remains the same as before.
*Arguments:. *
`m':
Pointer to an already initialized matrix object.
`nrow':
The number of rows in the resized matrix.
`ncol':
The number of columns in the resized matrix.
*Returns:. *
`'
Error code.
Time complexity: O(1) if the matrix gets smaller, usually O(n) if it
gets larger, n is the number of elements in the resized matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_resize_min --- Deallocates unused memory for a matrix_, Next: igraph_matrix_add_rows --- Adds rows to a matrix_, Prev: igraph_matrix_resize --- Resizes a matrix_, Up: Resizing operations <1>
7.3.13.2 igraph_matrix_resize_min -- Deallocates unused memory for a matrix.
............................................................................
int igraph_matrix_resize_min(igraph_matrix_t *m);
Note that this function might fail if there is not enough memory
available.
Also note, that this function leaves the matrix intact, i.e. it
does not destroy any of the elements. However, usually it involves
copying the matrix in memory.
*Arguments:. *
`m':
Pointer to an initialized matrix.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_matrix_resize()' (*note igraph_matrix_resize --- Resizes a
matrix_::).
Time complexity: operating system dependent.
File: igraph_reference_manual.info, Node: igraph_matrix_add_rows --- Adds rows to a matrix_, Next: igraph_matrix_add_cols --- Adds columns to a matrix_, Prev: igraph_matrix_resize_min --- Deallocates unused memory for a matrix_, Up: Resizing operations <1>
7.3.13.3 igraph_matrix_add_rows -- Adds rows to a matrix.
.........................................................
int igraph_matrix_add_rows(igraph_matrix_t *m, long int n);
*Arguments:. *
`m':
The matrix object.
`n':
The number of rows to add.
*Returns:. *
`'
Error code, `IGRAPH_ENOMEM' if there isn't enough memory for the
operation.
Time complexity: linear with the number of elements of the new,
resized matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_add_cols --- Adds columns to a matrix_, Next: igraph_matrix_remove_row --- Remove a row_, Prev: igraph_matrix_add_rows --- Adds rows to a matrix_, Up: Resizing operations <1>
7.3.13.4 igraph_matrix_add_cols -- Adds columns to a matrix.
............................................................
int igraph_matrix_add_cols(igraph_matrix_t *m, long int n);
*Arguments:. *
`m':
The matrix object.
`n':
The number of columns to add.
*Returns:. *
`'
Error code, `IGRAPH_ENOMEM' if there is not enough memory to
perform the operation.
Time complexity: linear with the number of elements of the new,
resized matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_remove_row --- Remove a row_, Next: igraph_matrix_remove_col --- Removes a column from a matrix_, Prev: igraph_matrix_add_cols --- Adds columns to a matrix_, Up: Resizing operations <1>
7.3.13.5 igraph_matrix_remove_row -- Remove a row.
..................................................
int igraph_matrix_remove_row(igraph_matrix_t *m, long int row);
A row is removed from the matrix.
*Arguments:. *
`m':
The input matrix.
`row':
The index of the row to remove.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_matrix_remove_col --- Removes a column from a matrix_, Prev: igraph_matrix_remove_row --- Remove a row_, Up: Resizing operations <1>
7.3.13.6 igraph_matrix_remove_col -- Removes a column from a matrix.
....................................................................
int igraph_matrix_remove_col(igraph_matrix_t *m, long int col);
*Arguments:. *
`m':
The matrix object.
`col':
The column to remove.
*Returns:. *
`'
Error code, always returns with success.
Time complexity: linear with the number of elements of the new,
resized matrix.
File: igraph_reference_manual.info, Node: Sparse matrices, Next: Sparse matrices; another kind, Prev: Matrices, Up: Data structure library; vector; matrix; other data types
7.4 Sparse matrices
===================
* Menu:
* About igraph_spmatrix_t objects::
* Sparse matrix constructors and destructors.: Sparse matrix constructors and destructors_.
* Accessing elements of a sparse matrix::
* Iterating over the non-zero elements of a sparse matrix::
* Matrix query operations::
* Matrix operations: Matrix operations <1>.
* Printing sparse matrices::
File: igraph_reference_manual.info, Node: About igraph_spmatrix_t objects, Next: Sparse matrix constructors and destructors_, Up: Sparse matrices
7.4.1 About igraph_spmatrix_t objects
-------------------------------------
The `igraph_spmatrix_t' type stores a sparse matrix with the assumption
that the number of nonzero elements in the matrix scales linearly with
the row or column count of the matrix (so most of the elements are
zero). Of course it can store an arbitrary real matrix, but if most of
the elements are nonzero, one should use `igraph_matrix_t' instead.
The elements are stored in column compressed format, so the elements
in the same column are stored adjacent in the computer's memory. The
storage requirement for a sparse matrix is O(n) where n is the number
of nonzero elements. Actually it can be a bit larger, see the
documentation of the vector type for an explanation.
File: igraph_reference_manual.info, Node: Sparse matrix constructors and destructors_, Next: Accessing elements of a sparse matrix, Prev: About igraph_spmatrix_t objects, Up: Sparse matrices
7.4.2 Sparse matrix constructors and destructors.
-------------------------------------------------
* Menu:
* igraph_spmatrix_init --- Initializes a sparse matrix.: igraph_spmatrix_init --- Initializes a sparse matrix_.
* igraph_spmatrix_copy --- Copies a sparse matrix.: igraph_spmatrix_copy --- Copies a sparse matrix_.
* igraph_spmatrix_destroy --- Destroys a sparse matrix object.: igraph_spmatrix_destroy --- Destroys a sparse matrix object_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_init --- Initializes a sparse matrix_, Next: igraph_spmatrix_copy --- Copies a sparse matrix_, Up: Sparse matrix constructors and destructors_
7.4.2.1 igraph_spmatrix_init -- Initializes a sparse matrix.
............................................................
int igraph_spmatrix_init(igraph_spmatrix_t *m, long int nrow, long int ncol);
Every sparse matrix needs to be initialized before using it, this is
done by calling this function. A matrix has to be destroyed if it is not
needed any more, see `igraph_spmatrix_destroy()' (*note
igraph_spmatrix_destroy --- Destroys a sparse matrix object_::).
*Arguments:. *
`m':
Pointer to a not yet initialized sparse matrix object to be
initialized.
`nrow':
The number of rows in the matrix.
`ncol':
The number of columns in the matrix.
*Returns:. *
`'
Error code.
Time complexity: operating system dependent.
File: igraph_reference_manual.info, Node: igraph_spmatrix_copy --- Copies a sparse matrix_, Next: igraph_spmatrix_destroy --- Destroys a sparse matrix object_, Prev: igraph_spmatrix_init --- Initializes a sparse matrix_, Up: Sparse matrix constructors and destructors_
7.4.2.2 igraph_spmatrix_copy -- Copies a sparse matrix.
.......................................................
int igraph_spmatrix_copy(igraph_spmatrix_t *to, const igraph_spmatrix_t *from);
Creates a sparse matrix object by copying another one.
*Arguments:. *
`to':
Pointer to an uninitialized sparse matrix object.
`from':
The initialized sparse matrix object to copy.
*Returns:. *
`'
Error code, `IGRAPH_ENOMEM' if there isn't enough memory to
allocate the new sparse matrix.
Time complexity: O(n), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_spmatrix_destroy --- Destroys a sparse matrix object_, Prev: igraph_spmatrix_copy --- Copies a sparse matrix_, Up: Sparse matrix constructors and destructors_
7.4.2.3 igraph_spmatrix_destroy -- Destroys a sparse matrix object.
...................................................................
void igraph_spmatrix_destroy(igraph_spmatrix_t *m);
This function frees all the memory allocated for a sparse matrix
object. The destroyed object needs to be reinitialized before using it
again.
*Arguments:. *
`m':
The matrix to destroy.
Time complexity: operating system dependent.
File: igraph_reference_manual.info, Node: Accessing elements of a sparse matrix, Next: Iterating over the non-zero elements of a sparse matrix, Prev: Sparse matrix constructors and destructors_, Up: Sparse matrices
7.4.3 Accessing elements of a sparse matrix
-------------------------------------------
* Menu:
* igraph_spmatrix_e --- Accessing an element of a sparse matrix.: igraph_spmatrix_e --- Accessing an element of a sparse matrix_.
* igraph_spmatrix_set --- Setting an element of a sparse matrix.: igraph_spmatrix_set --- Setting an element of a sparse matrix_.
* igraph_spmatrix_add_e --- Adding a real value to an element of a sparse matrix.: igraph_spmatrix_add_e --- Adding a real value to an element of a sparse matrix_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_e --- Accessing an element of a sparse matrix_, Next: igraph_spmatrix_set --- Setting an element of a sparse matrix_, Up: Accessing elements of a sparse matrix
7.4.3.1 igraph_spmatrix_e -- Accessing an element of a sparse matrix.
.....................................................................
igraph_real_t igraph_spmatrix_e(const igraph_spmatrix_t *m,
long int row, long int col);
Note that there are no range checks right now.
*Arguments:. *
`m':
The matrix object.
`row':
The index of the row, starting with zero.
`col':
The index of the column, starting with zero.
Time complexity: O(log n), where n is the number of nonzero elements
in the requested column.
File: igraph_reference_manual.info, Node: igraph_spmatrix_set --- Setting an element of a sparse matrix_, Next: igraph_spmatrix_add_e --- Adding a real value to an element of a sparse matrix_, Prev: igraph_spmatrix_e --- Accessing an element of a sparse matrix_, Up: Accessing elements of a sparse matrix
7.4.3.2 igraph_spmatrix_set -- Setting an element of a sparse matrix.
.....................................................................
int igraph_spmatrix_set(igraph_spmatrix_t *m, long int row, long int col,
igraph_real_t value);
Note that there are no range checks right now.
*Arguments:. *
`m':
The matrix object.
`row':
The index of the row, starting with zero.
`col':
The index of the column, starting with zero.
`value':
The new value.
Time complexity: O(log n), where n is the number of nonzero elements
in the requested column.
File: igraph_reference_manual.info, Node: igraph_spmatrix_add_e --- Adding a real value to an element of a sparse matrix_, Prev: igraph_spmatrix_set --- Setting an element of a sparse matrix_, Up: Accessing elements of a sparse matrix
7.4.3.3 igraph_spmatrix_add_e -- Adding a real value to an element of a sparse matrix.
......................................................................................
int igraph_spmatrix_add_e(igraph_spmatrix_t *m, long int row, long int col,
igraph_real_t value);
Note that there are no range checks right now. This is implemented
to avoid double lookup of a given element in the matrix by using
`igraph_spmatrix_e()' (*note igraph_spmatrix_e --- Accessing an element
of a sparse matrix_::) and `igraph_spmatrix_set()' (*note
igraph_spmatrix_set --- Setting an element of a sparse matrix_::)
consecutively.
*Arguments:. *
`m':
The matrix object.
`row':
The index of the row, starting with zero.
`col':
The index of the column, starting with zero.
`value':
The value to add.
Time complexity: O(log n), where n is the number of nonzero elements
in the requested column.
File: igraph_reference_manual.info, Node: Iterating over the non-zero elements of a sparse matrix, Next: Matrix query operations, Prev: Accessing elements of a sparse matrix, Up: Sparse matrices
7.4.4 Iterating over the non-zero elements of a sparse matrix
-------------------------------------------------------------
The `igraph_spmatrix_iter_t' type represents an iterator that can be
used to step over the non-zero elements of a sparse matrix in columnwise
order efficiently. In general, you shouldn't modify the elements of the
matrix while iterating over it; doing so will probably invalidate the
iterator, but there are no checks to prevent you from doing this.
To access the row index of the current element of the iterator, use
its `ri' field. Similarly, the `ci' field stores the column index of
the current element and the `value' field stores the value of the
element.
* Menu:
* igraph_spmatrix_iter_create --- Creates a sparse matrix iterator corresponding to the given matrix.: igraph_spmatrix_iter_create --- Creates a sparse matrix iterator corresponding to the given matrix_.
* igraph_spmatrix_iter_reset --- Resets a sparse matrix iterator.: igraph_spmatrix_iter_reset --- Resets a sparse matrix iterator_.
* igraph_spmatrix_iter_next --- Moves a sparse matrix iterator to the next nonzero element.: igraph_spmatrix_iter_next --- Moves a sparse matrix iterator to the next nonzero element_.
* igraph_spmatrix_iter_end --- Checks whether there are more elements in the iterator.: igraph_spmatrix_iter_end --- Checks whether there are more elements in the iterator_.
* igraph_spmatrix_iter_destroy --- Frees the memory used by the iterator.: igraph_spmatrix_iter_destroy --- Frees the memory used by the iterator_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_iter_create --- Creates a sparse matrix iterator corresponding to the given matrix_, Next: igraph_spmatrix_iter_reset --- Resets a sparse matrix iterator_, Up: Iterating over the non-zero elements of a sparse matrix
7.4.4.1 igraph_spmatrix_iter_create -- Creates a sparse matrix iterator corresponding to the given matrix.
..........................................................................................................
int igraph_spmatrix_iter_create(igraph_spmatrix_iter_t *mit, const igraph_spmatrix_t *m);
*Arguments:. *
`mit':
pointer to the matrix iterator being initialized
`m':
pointer to the matrix we will be iterating over
*Returns:. *
`'
Error code. The current implementation is always successful.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_iter_reset --- Resets a sparse matrix iterator_, Next: igraph_spmatrix_iter_next --- Moves a sparse matrix iterator to the next nonzero element_, Prev: igraph_spmatrix_iter_create --- Creates a sparse matrix iterator corresponding to the given matrix_, Up: Iterating over the non-zero elements of a sparse matrix
7.4.4.2 igraph_spmatrix_iter_reset -- Resets a sparse matrix iterator.
......................................................................
int igraph_spmatrix_iter_reset(igraph_spmatrix_iter_t *mit);
After resetting, the iterator will point to the first nonzero
element (if any).
*Arguments:. *
`mit':
pointer to the matrix iterator being reset
*Returns:. *
`'
Error code. The current implementation is always successful.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_iter_next --- Moves a sparse matrix iterator to the next nonzero element_, Next: igraph_spmatrix_iter_end --- Checks whether there are more elements in the iterator_, Prev: igraph_spmatrix_iter_reset --- Resets a sparse matrix iterator_, Up: Iterating over the non-zero elements of a sparse matrix
7.4.4.3 igraph_spmatrix_iter_next -- Moves a sparse matrix iterator to the next nonzero element.
................................................................................................
int igraph_spmatrix_iter_next(igraph_spmatrix_iter_t *mit);
You should call this function only if `igraph_spmatrix_iter_end()'
(*note igraph_spmatrix_iter_end --- Checks whether there are more
elements in the iterator_::) returns FALSE (0).
*Arguments:. *
`mit':
pointer to the matrix iterator being moved
*Returns:. *
`'
Error code. The current implementation is always successful.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_iter_end --- Checks whether there are more elements in the iterator_, Next: igraph_spmatrix_iter_destroy --- Frees the memory used by the iterator_, Prev: igraph_spmatrix_iter_next --- Moves a sparse matrix iterator to the next nonzero element_, Up: Iterating over the non-zero elements of a sparse matrix
7.4.4.4 igraph_spmatrix_iter_end -- Checks whether there are more elements in the iterator.
...........................................................................................
igraph_bool_t igraph_spmatrix_iter_end(igraph_spmatrix_iter_t *mit);
You should call this function before calling
`igraph_spmatrix_iter_next()' (*note igraph_spmatrix_iter_next ---
Moves a sparse matrix iterator to the next nonzero element_::) to make
sure you have more elements in the iterator.
*Arguments:. *
`mit':
pointer to the matrix iterator being checked
*Returns:. *
`'
TRUE (1) if there are more elements in the iterator, FALSE (0)
otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_iter_destroy --- Frees the memory used by the iterator_, Prev: igraph_spmatrix_iter_end --- Checks whether there are more elements in the iterator_, Up: Iterating over the non-zero elements of a sparse matrix
7.4.4.5 igraph_spmatrix_iter_destroy -- Frees the memory used by the iterator.
..............................................................................
void igraph_spmatrix_iter_destroy(igraph_spmatrix_iter_t *mit);
The current implementation does not allocate any memory upon
creation, so this function does nothing. However, since there is no
guarantee that future implementations will not allocate any memory in
`igraph_spmatrix_iter_create()' (*note igraph_spmatrix_iter_create ---
Creates a sparse matrix iterator corresponding to the given matrix_::),
you are still required to call this function whenever you are done with
the iterator.
*Arguments:. *
`mit':
pointer to the matrix iterator being destroyed
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Matrix query operations, Next: Matrix operations <1>, Prev: Iterating over the non-zero elements of a sparse matrix, Up: Sparse matrices
7.4.5 Matrix query operations
-----------------------------
* Menu:
* igraph_spmatrix_size --- The number of elements in a sparse matrix.: igraph_spmatrix_size --- The number of elements in a sparse matrix_.
* igraph_spmatrix_nrow --- The number of rows in a sparse matrix.: igraph_spmatrix_nrow --- The number of rows in a sparse matrix_.
* igraph_spmatrix_ncol --- The number of columns in a sparse matrix.: igraph_spmatrix_ncol --- The number of columns in a sparse matrix_.
* igraph_spmatrix_count_nonzero --- The number of non-zero elements in a sparse matrix.: igraph_spmatrix_count_nonzero --- The number of non-zero elements in a sparse matrix_.
* igraph_spmatrix_max --- Returns the maximum element of a matrix.: igraph_spmatrix_max --- Returns the maximum element of a matrix_.
* igraph_spmatrix_rowsums --- Calculates the row sums of the matrix.: igraph_spmatrix_rowsums --- Calculates the row sums of the matrix_.
* igraph_spmatrix_colsums --- Calculates the column sums of the matrix.: igraph_spmatrix_colsums --- Calculates the column sums of the matrix_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_size --- The number of elements in a sparse matrix_, Next: igraph_spmatrix_nrow --- The number of rows in a sparse matrix_, Up: Matrix query operations
7.4.5.1 igraph_spmatrix_size -- The number of elements in a sparse matrix.
..........................................................................
long int igraph_spmatrix_size(const igraph_spmatrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized sparse matrix object.
*Returns:. *
`'
The size of the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_nrow --- The number of rows in a sparse matrix_, Next: igraph_spmatrix_ncol --- The number of columns in a sparse matrix_, Prev: igraph_spmatrix_size --- The number of elements in a sparse matrix_, Up: Matrix query operations
7.4.5.2 igraph_spmatrix_nrow -- The number of rows in a sparse matrix.
......................................................................
long int igraph_spmatrix_nrow(const igraph_spmatrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized sparse matrix object.
*Returns:. *
`'
The number of rows in the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_ncol --- The number of columns in a sparse matrix_, Next: igraph_spmatrix_count_nonzero --- The number of non-zero elements in a sparse matrix_, Prev: igraph_spmatrix_nrow --- The number of rows in a sparse matrix_, Up: Matrix query operations
7.4.5.3 igraph_spmatrix_ncol -- The number of columns in a sparse matrix.
.........................................................................
long int igraph_spmatrix_ncol(const igraph_spmatrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized sparse matrix object.
*Returns:. *
`'
The number of columns in the sparse matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_count_nonzero --- The number of non-zero elements in a sparse matrix_, Next: igraph_spmatrix_max --- Returns the maximum element of a matrix_, Prev: igraph_spmatrix_ncol --- The number of columns in a sparse matrix_, Up: Matrix query operations
7.4.5.4 igraph_spmatrix_count_nonzero -- The number of non-zero elements in a sparse matrix.
............................................................................................
long int igraph_spmatrix_count_nonzero(const igraph_spmatrix_t *m);
*Arguments:. *
`m':
Pointer to an initialized sparse matrix object.
*Returns:. *
`'
The size of the matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_max --- Returns the maximum element of a matrix_, Next: igraph_spmatrix_rowsums --- Calculates the row sums of the matrix_, Prev: igraph_spmatrix_count_nonzero --- The number of non-zero elements in a sparse matrix_, Up: Matrix query operations
7.4.5.5 igraph_spmatrix_max -- Returns the maximum element of a matrix.
.......................................................................
igraph_real_t igraph_spmatrix_max(const igraph_spmatrix_t *m,
igraph_real_t *ridx, igraph_real_t *cidx);
If the matrix is empty, zero is returned.
*Arguments:. *
`m':
the matrix object.
`ridx':
the row index of the maximum element if not `NULL'.
`cidx':
the column index of the maximum element if not `NULL'.
Time complexity: O(n), the number of nonzero elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_spmatrix_rowsums --- Calculates the row sums of the matrix_, Next: igraph_spmatrix_colsums --- Calculates the column sums of the matrix_, Prev: igraph_spmatrix_max --- Returns the maximum element of a matrix_, Up: Matrix query operations
7.4.5.6 igraph_spmatrix_rowsums -- Calculates the row sums of the matrix.
.........................................................................
int igraph_spmatrix_rowsums(const igraph_spmatrix_t *m, igraph_vector_t *res);
*Arguments:. *
`m':
The matrix.
`res':
An initialized `igraph_vector_t', the result will be stored here.
The vector will be resized as needed.
Time complexity: O(n), the number of nonzero elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_spmatrix_colsums --- Calculates the column sums of the matrix_, Prev: igraph_spmatrix_rowsums --- Calculates the row sums of the matrix_, Up: Matrix query operations
7.4.5.7 igraph_spmatrix_colsums -- Calculates the column sums of the matrix.
............................................................................
int igraph_spmatrix_colsums(const igraph_spmatrix_t *m, igraph_vector_t *res);
*Arguments:. *
`m':
The matrix.
`res':
An initialized `igraph_vector_t', the result will be stored here.
The vector will be resized as needed.
Time complexity: O(n), the number of nonzero elements in the matrix.
File: igraph_reference_manual.info, Node: Matrix operations <1>, Next: Printing sparse matrices, Prev: Matrix query operations, Up: Sparse matrices
7.4.6 Matrix operations
-----------------------
* Menu:
* igraph_spmatrix_scale --- Multiplies each element of the sparse matrix by a constant.: igraph_spmatrix_scale --- Multiplies each element of the sparse matrix by a constant_.
* igraph_spmatrix_add_rows --- Adds rows to a sparse matrix.: igraph_spmatrix_add_rows --- Adds rows to a sparse matrix_.
* igraph_spmatrix_add_cols --- Adds columns to a sparse matrix.: igraph_spmatrix_add_cols --- Adds columns to a sparse matrix_.
* igraph_spmatrix_resize --- Resizes a sparse matrix.: igraph_spmatrix_resize --- Resizes a sparse matrix_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_scale --- Multiplies each element of the sparse matrix by a constant_, Next: igraph_spmatrix_add_rows --- Adds rows to a sparse matrix_, Up: Matrix operations <1>
7.4.6.1 igraph_spmatrix_scale -- Multiplies each element of the sparse matrix by a constant.
............................................................................................
void igraph_spmatrix_scale(igraph_spmatrix_t *m, igraph_real_t by);
*Arguments:. *
`m':
The matrix.
`by':
The constant.
Time complexity: O(n), the number of elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_spmatrix_add_rows --- Adds rows to a sparse matrix_, Next: igraph_spmatrix_add_cols --- Adds columns to a sparse matrix_, Prev: igraph_spmatrix_scale --- Multiplies each element of the sparse matrix by a constant_, Up: Matrix operations <1>
7.4.6.2 igraph_spmatrix_add_rows -- Adds rows to a sparse matrix.
.................................................................
int igraph_spmatrix_add_rows(igraph_spmatrix_t *m, long int n);
*Arguments:. *
`m':
The sparse matrix object.
`n':
The number of rows to add.
*Returns:. *
`'
Error code.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_add_cols --- Adds columns to a sparse matrix_, Next: igraph_spmatrix_resize --- Resizes a sparse matrix_, Prev: igraph_spmatrix_add_rows --- Adds rows to a sparse matrix_, Up: Matrix operations <1>
7.4.6.3 igraph_spmatrix_add_cols -- Adds columns to a sparse matrix.
....................................................................
int igraph_spmatrix_add_cols(igraph_spmatrix_t *m, long int n);
*Arguments:. *
`m':
The sparse matrix object.
`n':
The number of columns to add.
*Returns:. *
`'
Error code.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_spmatrix_resize --- Resizes a sparse matrix_, Prev: igraph_spmatrix_add_cols --- Adds columns to a sparse matrix_, Up: Matrix operations <1>
7.4.6.4 igraph_spmatrix_resize -- Resizes a sparse matrix.
..........................................................
int igraph_spmatrix_resize(igraph_spmatrix_t *m, long int nrow, long int ncol);
This function resizes a sparse matrix by adding more elements to it.
The matrix retains its data even after resizing it, except for the data
which lies outside the new boundaries (if the new size is smaller).
*Arguments:. *
`m':
Pointer to an already initialized sparse matrix object.
`nrow':
The number of rows in the resized matrix.
`ncol':
The number of columns in the resized matrix.
*Returns:. *
`'
Error code.
Time complexity: O(n). n is the number of elements in the old
matrix.
File: igraph_reference_manual.info, Node: Printing sparse matrices, Prev: Matrix operations <1>, Up: Sparse matrices
7.4.7 Printing sparse matrices
------------------------------
* Menu:
* igraph_spmatrix_print --- Prints a sparse matrix.: igraph_spmatrix_print --- Prints a sparse matrix_.
* igraph_spmatrix_fprint --- Prints a sparse matrix to the given file.: igraph_spmatrix_fprint --- Prints a sparse matrix to the given file_.
File: igraph_reference_manual.info, Node: igraph_spmatrix_print --- Prints a sparse matrix_, Next: igraph_spmatrix_fprint --- Prints a sparse matrix to the given file_, Up: Printing sparse matrices
7.4.7.1 igraph_spmatrix_print -- Prints a sparse matrix.
........................................................
int igraph_spmatrix_print(const igraph_spmatrix_t* matrix);
Prints a sparse matrix to the standard output. Only the non-zero
entries are printed.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of non-zero elements.
File: igraph_reference_manual.info, Node: igraph_spmatrix_fprint --- Prints a sparse matrix to the given file_, Prev: igraph_spmatrix_print --- Prints a sparse matrix_, Up: Printing sparse matrices
7.4.7.2 igraph_spmatrix_fprint -- Prints a sparse matrix to the given file.
...........................................................................
int igraph_spmatrix_fprint(const igraph_spmatrix_t* matrix, FILE *file);
Prints a sparse matrix to the given file. Only the non-zero entries
are printed.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of non-zero elements.
File: igraph_reference_manual.info, Node: Sparse matrices; another kind, Next: Stacks, Prev: Sparse matrices, Up: Data structure library; vector; matrix; other data types
7.5 Sparse matrices, another kind
=================================
* Menu:
* About sparse matrices : About sparse matrices.
* Creating sparse matrix objects::
* Query properties of a sparse matrix::
* Operations on sprase matrices::
* Operations that change the internal representation::
* Decompositions and solving linear systems::
* Eigenvalues and eigenvectors::
* Conversion to other data types::
* Writing to a file, or to the screen: Writing to a file; or to the screen.
File: igraph_reference_manual.info, Node: About sparse matrices, Next: Creating sparse matrix objects, Up: Sparse matrices; another kind
7.5.1 About sparse matrices
---------------------------
The ` igraph_sparsemat_t' data type stores sparse matrices, i.e.
matrices in which the majority of the elements are zero.
The data type is essentially a wrapper to some of the functions in
the CXSparse library, by Tim Davis, see
http://www.cise.ufl.edu/research/sparse/CXSparse/
(http://www.cise.ufl.edu/research/sparse/CXSparse/)
Matrices can be stored in two formats: triplet and
column-compressed. The triplet format is intended for sparse matrix
initialization, as it is easy to add new (non-zero) elements to it.
Most of the computations are done on sparse matrices in
column-compressed format, after the user has converted the triplet
matrix to column-compressed, via `igraph_sparsemat_compress()' (*note
igraph_sparsemat_compress --- Compress a sparse matrix; i_e_ convert it
to column-compress format::).
Both formats are dynamic, in the sense that new elements can be
added to them, possibly resulting the allocation of more memory.
Row and column indices follow the C convention and are zero-based.
* File examples/simple/igraph_sparsemat.c*
* File examples/simple/igraph_sparsemat2.c*
* File examples/simple/igraph_sparsemat3.c*
* File examples/simple/igraph_sparsemat4.c*
* File examples/simple/igraph_sparsemat5.c*
* File examples/simple/igraph_sparsemat6.c*
* File examples/simple/igraph_sparsemat7.c*
* File examples/simple/igraph_sparsemat8.c*
File: igraph_reference_manual.info, Node: Creating sparse matrix objects, Next: Query properties of a sparse matrix, Prev: About sparse matrices, Up: Sparse matrices; another kind
7.5.2 Creating sparse matrix objects
------------------------------------
* Menu:
* igraph_sparsemat_init --- Initialize a sparse matrix, in triplet format: igraph_sparsemat_init --- Initialize a sparse matrix; in triplet format.
* igraph_sparsemat_copy --- Copy a sparse matrix::
* igraph_sparsemat_realloc --- Allocate more (or less) memory for a sparse matrix: igraph_sparsemat_realloc --- Allocate more [or less] memory for a sparse matrix.
* igraph_sparsemat_destroy --- Deallocate memory used by a sparse matrix::
* igraph_sparsemat_eye --- Create a sparse identity matrix::
* igraph_sparsemat_diag --- Create a sparse diagonal matrix::
File: igraph_reference_manual.info, Node: igraph_sparsemat_init --- Initialize a sparse matrix; in triplet format, Next: igraph_sparsemat_copy --- Copy a sparse matrix, Up: Creating sparse matrix objects
7.5.2.1 igraph_sparsemat_init -- Initialize a sparse matrix, in triplet format
..............................................................................
int igraph_sparsemat_init(igraph_sparsemat_t *A, int rows, int cols, int nzmax);
This is the most common way to create a sparse matrix, together with
the `igraph_sparsemat_entry()' (*note igraph_sparsemat_entry --- Add an
element to a sparse matrix::) function, which can be used to add the
non-zero elements one by one. Once done, the user can call
`igraph_sparsemat_compress()' (*note igraph_sparsemat_compress ---
Compress a sparse matrix; i_e_ convert it to column-compress format::)
to convert the matrix to column-compressed, to allow computations with
it.
The user must call `igraph_sparsemat_destroy()' (*note
igraph_sparsemat_destroy --- Deallocate memory used by a sparse
matrix::) on the matrix to deallocate the memory, once the matrix is no
more needed.
*Arguments:. *
`A':
Pointer to a not yet initialized sparse matrix.
`rows':
The number of rows in the matrix.
`cols':
The number of columns.
`nzmax':
The maximum number of non-zero elements in the matrix. It is not
compulsory to get this right, but it is useful for the allocation
of the proper amount of memory.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_copy --- Copy a sparse matrix, Next: igraph_sparsemat_realloc --- Allocate more [or less] memory for a sparse matrix, Prev: igraph_sparsemat_init --- Initialize a sparse matrix; in triplet format, Up: Creating sparse matrix objects
7.5.2.2 igraph_sparsemat_copy -- Copy a sparse matrix
.....................................................
int igraph_sparsemat_copy(igraph_sparsemat_t *to,
const igraph_sparsemat_t *from);
Create a sparse matrix object, by copying another one. The source
matrix can be either in triplet or column-compressed format.
Exactly the same amount of memory will be allocated to the copy
matrix, as it is currently for the original one.
*Arguments:. *
`to':
Pointer to an uninitialized sparse matrix, the copy will be
created here.
`from':
The sparse matrix to copy.
*Returns:. *
`'
Error code.
Time complexity: O(n+nzmax), the number of columns plus the maximum
number of non-zero elements.
File: igraph_reference_manual.info, Node: igraph_sparsemat_realloc --- Allocate more [or less] memory for a sparse matrix, Next: igraph_sparsemat_destroy --- Deallocate memory used by a sparse matrix, Prev: igraph_sparsemat_copy --- Copy a sparse matrix, Up: Creating sparse matrix objects
7.5.2.3 igraph_sparsemat_realloc -- Allocate more (or less) memory for a sparse matrix
......................................................................................
int igraph_sparsemat_realloc(igraph_sparsemat_t *A, int nzmax);
Sparse matrices automatically allocate more memory, as needed. To
control memory allocation, the user can call this function, to allocate
memory for a given number of non-zero elements.
*Arguments:. *
`A':
The sparse matrix, it can be in triplet or column-compressed
format.
`nzmax':
The new maximum number of non-zero elements.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_destroy --- Deallocate memory used by a sparse matrix, Next: igraph_sparsemat_eye --- Create a sparse identity matrix, Prev: igraph_sparsemat_realloc --- Allocate more [or less] memory for a sparse matrix, Up: Creating sparse matrix objects
7.5.2.4 igraph_sparsemat_destroy -- Deallocate memory used by a sparse matrix
.............................................................................
void igraph_sparsemat_destroy(igraph_sparsemat_t *A);
One destroyed, the sparse matrix must be initialized again, before
calling any other operation on it.
*Arguments:. *
`A':
The sparse matrix to destroy.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_eye --- Create a sparse identity matrix, Next: igraph_sparsemat_diag --- Create a sparse diagonal matrix, Prev: igraph_sparsemat_destroy --- Deallocate memory used by a sparse matrix, Up: Creating sparse matrix objects
7.5.2.5 igraph_sparsemat_eye -- Create a sparse identity matrix
...............................................................
int igraph_sparsemat_eye(igraph_sparsemat_t *A, int n, int nzmax,
igraph_real_t value,
igraph_bool_t compress);
*Arguments:. *
`A':
An uninitialized sparse matrix, the result is stored here.
`n':
The number of rows and number of columns in the matrix.
`nzmax':
The maximum number of non-zero elements, this essentially gives
the amount of memory that will be allocated for matrix elements.
`value':
The value to store in the diagonal.
`compress':
Whether to create a column-compressed matrix. If false, then a
triplet matrix is created.
*Returns:. *
`'
Error code.
Time complexity: O(n).
File: igraph_reference_manual.info, Node: igraph_sparsemat_diag --- Create a sparse diagonal matrix, Prev: igraph_sparsemat_eye --- Create a sparse identity matrix, Up: Creating sparse matrix objects
7.5.2.6 igraph_sparsemat_diag -- Create a sparse diagonal matrix
................................................................
int igraph_sparsemat_diag(igraph_sparsemat_t *A, int nzmax,
const igraph_vector_t *values,
igraph_bool_t compress);
*Arguments:. *
`A':
An uninitialized sparse matrix, the result is stored here.
`nzmax':
The maximum number of non-zero elements, this essentially gives
the amount of memory that will be allocated for matrix elements.
`values':
The values to store in the diagonal, the size of the matrix
defined by the length of this vector.
`compress':
Whether to create a column-compressed matrix. If false, then a
triplet matrix is created.
*Returns:. *
`'
Error code.
Time complexity: O(n), the length of the diagonal vector.
File: igraph_reference_manual.info, Node: Query properties of a sparse matrix, Next: Operations on sprase matrices, Prev: Creating sparse matrix objects, Up: Sparse matrices; another kind
7.5.3 Query properties of a sparse matrix
-----------------------------------------
* Menu:
* igraph_sparsemat_index --- Index a sparse matrix, extract a submatrix, or a single element: igraph_sparsemat_index --- Index a sparse matrix; extract a submatrix; or a single element.
* igraph_sparsemat_nrow --- Number of rows::
* igraph_sparsemat_ncol --- Number of columns.: igraph_sparsemat_ncol --- Number of columns_.
* igraph_sparsemat_type --- Type of a sparse matrix (triplet or column-compressed): igraph_sparsemat_type --- Type of a sparse matrix [triplet or column-compressed].
* igraph_sparsemat_is_triplet --- Is this sparse matrix in triplet format?::
* igraph_sparsemat_is_cc --- Is this sparse matrix in column-compressed format?::
File: igraph_reference_manual.info, Node: igraph_sparsemat_index --- Index a sparse matrix; extract a submatrix; or a single element, Next: igraph_sparsemat_nrow --- Number of rows, Up: Query properties of a sparse matrix
7.5.3.1 igraph_sparsemat_index -- Index a sparse matrix, extract a submatrix, or a single element
.................................................................................................
int igraph_sparsemat_index(const igraph_sparsemat_t *A,
const igraph_vector_int_t *p,
const igraph_vector_int_t *q,
igraph_sparsemat_t *res,
igraph_real_t *constres);
This function serves two purposes. First, it can extract submatrices
from a sparse matrix. Second, as a special case, it can extract a
single element from a sparse matrix.
*Arguments:. *
`A':
The input matrix, it must be in column-compressed format.
`p':
An integer vector, or a null pointer. The selected row index or
indices. A null pointer selects all rows.
`q':
An integer vector, or a null pointer. The selected column index or
indices. A null pointer selects all columns.
`res':
Pointer to an uninitialized sparse matrix, or a null pointer. If
not a null pointer, then the selected submatrix is stored here.
`constres':
Pointer to a real variable or a null pointer. If not a null
pointer, then the first non-zero element in the selected submatrix
is stored here, if there is one. Otherwise zero is stored here.
This behavior is handy if one wants to select a single entry from
the matrix.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_nrow --- Number of rows, Next: igraph_sparsemat_ncol --- Number of columns_, Prev: igraph_sparsemat_index --- Index a sparse matrix; extract a submatrix; or a single element, Up: Query properties of a sparse matrix
7.5.3.2 igraph_sparsemat_nrow -- Number of rows
...............................................
long int igraph_sparsemat_nrow(const igraph_sparsemat_t *A);
*Arguments:. *
`A':
The input matrix, in triplet or column-compressed format.
*Returns:. *
`'
The number of rows in the `A' matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_ncol --- Number of columns_, Next: igraph_sparsemat_type --- Type of a sparse matrix [triplet or column-compressed], Prev: igraph_sparsemat_nrow --- Number of rows, Up: Query properties of a sparse matrix
7.5.3.3 igraph_sparsemat_ncol -- Number of columns.
...................................................
long int igraph_sparsemat_ncol(const igraph_sparsemat_t *A);
*Arguments:. *
`A':
The input matrix, in triplet or column-compressed format.
*Returns:. *
`'
The number of columns in the `A' matrix.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_type --- Type of a sparse matrix [triplet or column-compressed], Next: igraph_sparsemat_is_triplet --- Is this sparse matrix in triplet format?, Prev: igraph_sparsemat_ncol --- Number of columns_, Up: Query properties of a sparse matrix
7.5.3.4 igraph_sparsemat_type -- Type of a sparse matrix (triplet or column-compressed)
.......................................................................................
igraph_sparsemat_type_t igraph_sparsemat_type(const igraph_sparsemat_t *A);
Gives whether a sparse matrix is stored in the triplet format or in
column-compressed format.
*Arguments:. *
`A':
The input matrix.
*Returns:. *
`'
Either `IGRAPH_SPARSEMAT_CC' or `IGRAPH_SPARSEMAT_TRIPLET'.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_is_triplet --- Is this sparse matrix in triplet format?, Next: igraph_sparsemat_is_cc --- Is this sparse matrix in column-compressed format?, Prev: igraph_sparsemat_type --- Type of a sparse matrix [triplet or column-compressed], Up: Query properties of a sparse matrix
7.5.3.5 igraph_sparsemat_is_triplet -- Is this sparse matrix in triplet format?
...............................................................................
igraph_bool_t igraph_sparsemat_is_triplet(const igraph_sparsemat_t *A);
Decides whether a sparse matrix is in triplet format.
*Arguments:. *
`A':
The input matrix.
*Returns:. *
`'
One if the input matrix is in triplet format, zero otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_is_cc --- Is this sparse matrix in column-compressed format?, Prev: igraph_sparsemat_is_triplet --- Is this sparse matrix in triplet format?, Up: Query properties of a sparse matrix
7.5.3.6 igraph_sparsemat_is_cc -- Is this sparse matrix in column-compressed format?
....................................................................................
igraph_bool_t igraph_sparsemat_is_cc(const igraph_sparsemat_t *A);
Decides whether a sparse matrix is in column-compressed format.
*Arguments:. *
`A':
The input matrix.
*Returns:. *
`'
One if the input matrix is in column-compressed format, zero
otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Operations on sprase matrices, Next: Operations that change the internal representation, Prev: Query properties of a sparse matrix, Up: Sparse matrices; another kind
7.5.4 Operations on sprase matrices
-----------------------------------
* Menu:
* igraph_sparsemat_entry --- Add an element to a sparse matrix::
* igraph_sparsemat_fkeep --- Filter the elements of a sparse matrix::
* igraph_sparsemat_dropzeros --- Drop the zero elements from a sparse matrix::
* igraph_sparsemat_droptol --- Drop the almost zero elements of a sparse matrix::
* igraph_sparsemat_scale --- Scale a sparse matrix::
* igraph_sparsemat_permute --- Permute the rows and columns of a sparse matrix::
* igraph_sparsemat_transpose --- Transpose a sparse matrix::
* igraph_sparsemat_add --- Sum of two sparse matrices::
* igraph_sparsemat_multiply --- Matrix multiplication::
* igraph_sparsemat_gaxpy --- Matrix-vector product, added to another vector.: igraph_sparsemat_gaxpy --- Matrix-vector product; added to another vector_.
* igraph_sparsemat_add_rows --- Add rows to a sparse matrix::
* igraph_sparsemat_add_cols --- Add columns to a sparse matrix::
* igraph_sparsemat_resize --- Resize a sparse matrix::
File: igraph_reference_manual.info, Node: igraph_sparsemat_entry --- Add an element to a sparse matrix, Next: igraph_sparsemat_fkeep --- Filter the elements of a sparse matrix, Up: Operations on sprase matrices
7.5.4.1 igraph_sparsemat_entry -- Add an element to a sparse matrix
...................................................................
int igraph_sparsemat_entry(igraph_sparsemat_t *A, int row, int col,
igraph_real_t elem);
This function can be used to add the entries to a sparse matrix,
after initializing it with `igraph_sparsemat_init()' (*note
igraph_sparsemat_init --- Initialize a sparse matrix; in triplet
format::).
*Arguments:. *
`A':
The input matrix, it must be in triplet format.
`row':
The row index of the entry to add.
`col':
The column index of the entry to add.
`elem':
The value of the entry.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_fkeep --- Filter the elements of a sparse matrix, Next: igraph_sparsemat_dropzeros --- Drop the zero elements from a sparse matrix, Prev: igraph_sparsemat_entry --- Add an element to a sparse matrix, Up: Operations on sprase matrices
7.5.4.2 igraph_sparsemat_fkeep -- Filter the elements of a sparse matrix
........................................................................
int igraph_sparsemat_fkeep(igraph_sparsemat_t *A,
int (*fkeep)(int, int, igraph_real_t, void*),
void *other);
This function can be used to filter the (non-zero) elements of a
sparse matrix. For all entries, it calls the supplied function and
depending on the return values either keeps, or deleted the element
from the matrix.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`fkeep':
The filter function. It must take four arguments: the first is an
`int', the row index of the entry, the second is another `int',
the column index. The third is `igraph_real_t', the value of the
entry. The fourth element is a `void' pointer, the `other'
argument is passed here. The function must return an `int'. If
this is zero, then the entry is deleted, otherwise it is kept.
`other':
A `void' pointer that is passed to the filtering function.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_dropzeros --- Drop the zero elements from a sparse matrix, Next: igraph_sparsemat_droptol --- Drop the almost zero elements of a sparse matrix, Prev: igraph_sparsemat_fkeep --- Filter the elements of a sparse matrix, Up: Operations on sprase matrices
7.5.4.3 igraph_sparsemat_dropzeros -- Drop the zero elements from a sparse matrix
.................................................................................
int igraph_sparsemat_dropzeros(igraph_sparsemat_t *A);
As a result of matrix operations, some of the entries in a sparse
matrix might be zero. This function removes these entries.
*Arguments:. *
`A':
The input matrix, it must be in column-compressed format.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_droptol --- Drop the almost zero elements of a sparse matrix, Next: igraph_sparsemat_scale --- Scale a sparse matrix, Prev: igraph_sparsemat_dropzeros --- Drop the zero elements from a sparse matrix, Up: Operations on sprase matrices
7.5.4.4 igraph_sparsemat_droptol -- Drop the almost zero elements of a sparse matrix
....................................................................................
int igraph_sparsemat_droptol(igraph_sparsemat_t *A, igraph_real_t tol);
This function is similar to `igraph_sparsemat_dropzeros()' (*note
igraph_sparsemat_dropzeros --- Drop the zero elements from a sparse
matrix::), but it also drops entries that are closer to zero than the
given tolerance threshold.
*Arguments:. *
`A':
The input matrix, it must be in column-compressed format.
`tol':
Real number, giving the tolerance threshold.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_scale --- Scale a sparse matrix, Next: igraph_sparsemat_permute --- Permute the rows and columns of a sparse matrix, Prev: igraph_sparsemat_droptol --- Drop the almost zero elements of a sparse matrix, Up: Operations on sprase matrices
7.5.4.5 igraph_sparsemat_scale -- Scale a sparse matrix
.......................................................
int igraph_sparsemat_scale(igraph_sparsemat_t *A, igraph_real_t by);
Multiplies all elements of a sparse matrix, by the given scalar.
*Arguments:. *
`A':
The input matrix.
`by':
The scaling factor.
*Returns:. *
`'
Error code.
Time complexity: O(nz), the number of non-zero elements in the
matrix.
File: igraph_reference_manual.info, Node: igraph_sparsemat_permute --- Permute the rows and columns of a sparse matrix, Next: igraph_sparsemat_transpose --- Transpose a sparse matrix, Prev: igraph_sparsemat_scale --- Scale a sparse matrix, Up: Operations on sprase matrices
7.5.4.6 igraph_sparsemat_permute -- Permute the rows and columns of a sparse matrix
...................................................................................
int igraph_sparsemat_permute(const igraph_sparsemat_t *A,
const igraph_vector_int_t *p,
const igraph_vector_int_t *q,
igraph_sparsemat_t *res);
*Arguments:. *
`A':
The input matrix, it must be in column-compressed format.
`p':
Integer vector, giving the permutation of the rows.
`q':
Integer vector, the permutation of the columns.
`res':
Pointer to an uninitialized sparse matrix, the result is stored
here.
*Returns:. *
`'
Error code.
Time complexity: O(m+n+nz), the number of rows plus the number of
columns plus the number of non-zero elements in the matrix.
File: igraph_reference_manual.info, Node: igraph_sparsemat_transpose --- Transpose a sparse matrix, Next: igraph_sparsemat_add --- Sum of two sparse matrices, Prev: igraph_sparsemat_permute --- Permute the rows and columns of a sparse matrix, Up: Operations on sprase matrices
7.5.4.7 igraph_sparsemat_transpose -- Transpose a sparse matrix
...............................................................
int igraph_sparsemat_transpose(const igraph_sparsemat_t *A,
igraph_sparsemat_t *res,
int values);
*Arguments:. *
`A':
The input matrix, column-compressed or triple format.
`res':
Pointer to an uninitialized sparse matrix, the result is stored
here.
`values':
If this is non-zero, the matrix transpose is calculated the normal
way. If it is zero, then only the pattern of the input matrix is
stored in the result, the values are not.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_add --- Sum of two sparse matrices, Next: igraph_sparsemat_multiply --- Matrix multiplication, Prev: igraph_sparsemat_transpose --- Transpose a sparse matrix, Up: Operations on sprase matrices
7.5.4.8 igraph_sparsemat_add -- Sum of two sparse matrices
..........................................................
int igraph_sparsemat_add(const igraph_sparsemat_t *A,
const igraph_sparsemat_t *B,
igraph_real_t alpha,
igraph_real_t beta,
igraph_sparsemat_t *res);
*Arguments:. *
`A':
The first input matrix, in column-compressed format.
`B':
The second input matrix, in column-compressed format.
`alpha':
Real scalar, `A' is multiplied by `alpha' before the addition.
`beta':
Real scalar, `B' is multiplied by `beta' before the addition.
`res':
Pointer to an uninitialized sparse matrix, the result is stored
here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_multiply --- Matrix multiplication, Next: igraph_sparsemat_gaxpy --- Matrix-vector product; added to another vector_, Prev: igraph_sparsemat_add --- Sum of two sparse matrices, Up: Operations on sprase matrices
7.5.4.9 igraph_sparsemat_multiply -- Matrix multiplication
..........................................................
int igraph_sparsemat_multiply(const igraph_sparsemat_t *A,
const igraph_sparsemat_t *B,
igraph_sparsemat_t *res);
Multiplies two sparse matrices.
*Arguments:. *
`A':
The first input matrix (left hand side), in column-compressed
format.
`B':
The second input matrix (right hand side), in column-compressed
format.
`res':
Pointer to an uninitialized sparse matrix, the result is stored
here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_gaxpy --- Matrix-vector product; added to another vector_, Next: igraph_sparsemat_add_rows --- Add rows to a sparse matrix, Prev: igraph_sparsemat_multiply --- Matrix multiplication, Up: Operations on sprase matrices
7.5.4.10 igraph_sparsemat_gaxpy -- Matrix-vector product, added to another vector.
..................................................................................
int igraph_sparsemat_gaxpy(const igraph_sparsemat_t *A,
const igraph_vector_t *x,
igraph_vector_t *res);
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`x':
The input vector, its size must match the number of columns in `A'.
`res':
This vector is added to the matrix-vector product and it is
overwritten by the result.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_add_rows --- Add rows to a sparse matrix, Next: igraph_sparsemat_add_cols --- Add columns to a sparse matrix, Prev: igraph_sparsemat_gaxpy --- Matrix-vector product; added to another vector_, Up: Operations on sprase matrices
7.5.4.11 igraph_sparsemat_add_rows -- Add rows to a sparse matrix
.................................................................
int igraph_sparsemat_add_rows(igraph_sparsemat_t *A, long int n);
The current matrix elements are retained and all elements in the new
rows are zero.
*Arguments:. *
`A':
The input matrix, in triplet or column-compressed format.
`n':
The number of rows to add.
*Returns:. *
`'
Error code.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_add_cols --- Add columns to a sparse matrix, Next: igraph_sparsemat_resize --- Resize a sparse matrix, Prev: igraph_sparsemat_add_rows --- Add rows to a sparse matrix, Up: Operations on sprase matrices
7.5.4.12 igraph_sparsemat_add_cols -- Add columns to a sparse matrix
....................................................................
int igraph_sparsemat_add_cols(igraph_sparsemat_t *A, long int n);
The current matrix elements are retained, and all elements in the
new columns are zero.
*Arguments:. *
`A':
The input matrix, in triplet or column-compressed format.
`n':
The number of columns to add.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_resize --- Resize a sparse matrix, Prev: igraph_sparsemat_add_cols --- Add columns to a sparse matrix, Up: Operations on sprase matrices
7.5.4.13 igraph_sparsemat_resize -- Resize a sparse matrix
..........................................................
int igraph_sparsemat_resize(igraph_sparsemat_t *A, long int nrow,
long int ncol, int nzmax);
This function resizes a sparse matrix. The resized sparse matrix
will be empty.
*Arguments:. *
`A':
The initialized sparse matrix to resize.
`nrow':
The new number of rows.
`ncol':
The new number of columns.
`nzmax':
The new maximum number of elements.
*Returns:. *
`'
Error code.
Time complexity: O(nzmax), the maximum number of non-zero elements.
File: igraph_reference_manual.info, Node: Operations that change the internal representation, Next: Decompositions and solving linear systems, Prev: Operations on sprase matrices, Up: Sparse matrices; another kind
7.5.5 Operations that change the internal representation
--------------------------------------------------------
* Menu:
* igraph_sparsemat_compress --- Compress a sparse matrix, i.e. convert it to column-compress format: igraph_sparsemat_compress --- Compress a sparse matrix; i_e_ convert it to column-compress format.
* igraph_sparsemat_dupl --- Remove duplicate elements from a sparse matrix::
File: igraph_reference_manual.info, Node: igraph_sparsemat_compress --- Compress a sparse matrix; i_e_ convert it to column-compress format, Next: igraph_sparsemat_dupl --- Remove duplicate elements from a sparse matrix, Up: Operations that change the internal representation
7.5.5.1 igraph_sparsemat_compress -- Compress a sparse matrix, i.e. convert it to column-compress format
........................................................................................................
int igraph_sparsemat_compress(const igraph_sparsemat_t *A,
igraph_sparsemat_t *res);
Almost all sparse matrix operations require that the matrix is in
column-compressed format.
*Arguments:. *
`A':
The input matrix, it must be in triplet format.
`res':
Pointer to an uninitialized sparse matrix object, the compressed
version of `A' is stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_dupl --- Remove duplicate elements from a sparse matrix, Prev: igraph_sparsemat_compress --- Compress a sparse matrix; i_e_ convert it to column-compress format, Up: Operations that change the internal representation
7.5.5.2 igraph_sparsemat_dupl -- Remove duplicate elements from a sparse matrix
...............................................................................
int igraph_sparsemat_dupl(igraph_sparsemat_t *A);
It is possible that a column-compressed sparse matrix stores a
single matrix entry in multiple pieces. The entry is then the sum of
all its pieces. (Some functions create matrices like this.) This
function eliminates the multiple pieces.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: Decompositions and solving linear systems, Next: Eigenvalues and eigenvectors, Prev: Operations that change the internal representation, Up: Sparse matrices; another kind
7.5.6 Decompositions and solving linear systems
-----------------------------------------------
* Menu:
* igraph_sparsemat_symblu --- Symbolic LU decomposition::
* igraph_sparsemat_symbqr --- Symbolic QR decomposition::
* igraph_sparsemat_lsolve --- Solve a lower-triangular linear system::
* igraph_sparsemat_ltsolve --- Solve an upper-triangular linear system::
* igraph_sparsemat_usolve --- Solve an upper-triangular linear system::
* igraph_sparsemat_utsolve --- Solve a lower-triangular linear system::
* igraph_sparsemat_cholsol --- Solve a symmetric linear system via Cholesky decomposition::
* igraph_sparsemat_lusol --- Solve a linear system via LU decomposition::
* igraph_sparsemat_lu --- LU decomposition of a sparse matrix::
* igraph_sparsemat_qr --- QR decomposition of a sparse matrix::
* igraph_sparsemat_luresol --- Solve linear system using a precomputed LU decomposition::
* igraph_sparsemat_qrresol --- Solve a linear system using a precomputed QR decomposition::
* igraph_sparsemat_symbolic_destroy --- Deallocate memory for a symbolic decomposition::
* igraph_sparsemat_numeric_destroy --- Deallocate memory for a numeric decomposition::
File: igraph_reference_manual.info, Node: igraph_sparsemat_symblu --- Symbolic LU decomposition, Next: igraph_sparsemat_symbqr --- Symbolic QR decomposition, Up: Decompositions and solving linear systems
7.5.6.1 igraph_sparsemat_symblu -- Symbolic LU decomposition
............................................................
int igraph_sparsemat_symblu(long int order, const igraph_sparsemat_t *A,
igraph_sparsemat_symbolic_t *dis);
LU decomposition of sparse matrices involves two steps, the first is
calling this function, and then `igraph_sparsemat_lu()' (*note
igraph_sparsemat_lu --- LU decomposition of a sparse matrix::).
*Arguments:. *
`order':
The ordering to use: 0 means natural ordering, 1 means minimum
degree ordering of A+A', 2 is minimum degree ordering of A'A after
removing the dense rows from A, and 3 is the minimum degree
ordering of A'A.
`A':
The input matrix, in column-compressed format.
`dis':
The result of the symbolic analysis is stored here. Once not
needed anymore, it must be destroyed by calling
`igraph_sparsemat_symbolic_destroy()' (*note
igraph_sparsemat_symbolic_destroy --- Deallocate memory for a
symbolic decomposition::).
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_symbqr --- Symbolic QR decomposition, Next: igraph_sparsemat_lsolve --- Solve a lower-triangular linear system, Prev: igraph_sparsemat_symblu --- Symbolic LU decomposition, Up: Decompositions and solving linear systems
7.5.6.2 igraph_sparsemat_symbqr -- Symbolic QR decomposition
............................................................
int igraph_sparsemat_symbqr(long int order, const igraph_sparsemat_t *A,
igraph_sparsemat_symbolic_t *dis);
QR decomposition of sparse matrices involves two steps, the first is
calling this function, and then `igraph_sparsemat_qr()' (*note
igraph_sparsemat_qr --- QR decomposition of a sparse matrix::).
*Arguments:. *
`order':
The ordering to use: 0 means natural ordering, 1 means minimum
degree ordering of A+A', 2 is minimum degree ordering of A'A after
removing the dense rows from A, and 3 is the minimum degree
ordering of A'A.
`A':
The input matrix, in column-compressed format.
`dis':
The result of the symbolic analysis is stored here. Once not
needed anymore, it must be destroyed by calling
`igraph_sparsemat_symbolic_destroy()' (*note
igraph_sparsemat_symbolic_destroy --- Deallocate memory for a
symbolic decomposition::).
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_lsolve --- Solve a lower-triangular linear system, Next: igraph_sparsemat_ltsolve --- Solve an upper-triangular linear system, Prev: igraph_sparsemat_symbqr --- Symbolic QR decomposition, Up: Decompositions and solving linear systems
7.5.6.3 igraph_sparsemat_lsolve -- Solve a lower-triangular linear system
.........................................................................
int igraph_sparsemat_lsolve(const igraph_sparsemat_t *L,
const igraph_vector_t *b,
igraph_vector_t *res);
Solve the Lx=b linear equation system, where the L coefficient
matrix is square and lower-triangular, with a zero-free diagonal.
*Arguments:. *
`L':
The input matrix, in column-compressed format.
`b':
The right hand side of the linear system.
`res':
An initialized vector, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_ltsolve --- Solve an upper-triangular linear system, Next: igraph_sparsemat_usolve --- Solve an upper-triangular linear system, Prev: igraph_sparsemat_lsolve --- Solve a lower-triangular linear system, Up: Decompositions and solving linear systems
7.5.6.4 igraph_sparsemat_ltsolve -- Solve an upper-triangular linear system
...........................................................................
int igraph_sparsemat_ltsolve(const igraph_sparsemat_t *L,
const igraph_vector_t *b,
igraph_vector_t *res);
Solve the L'x=b linear equation system, where the L matrix is square
and lower-triangular, with a zero-free diagonal.
*Arguments:. *
`L':
The input matrix, in column-compressed format.
`b':
The right hand side of the linear system.
`res':
An initialized vector, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_usolve --- Solve an upper-triangular linear system, Next: igraph_sparsemat_utsolve --- Solve a lower-triangular linear system, Prev: igraph_sparsemat_ltsolve --- Solve an upper-triangular linear system, Up: Decompositions and solving linear systems
7.5.6.5 igraph_sparsemat_usolve -- Solve an upper-triangular linear system
..........................................................................
int igraph_sparsemat_usolve(const igraph_sparsemat_t *U,
const igraph_vector_t *b,
igraph_vector_t *res);
Solves the Ux=b upper triangular system.
*Arguments:. *
`U':
The input matrix, in column-compressed format.
`b':
The right hand side of the linear system.
`res':
An initialized vector, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_utsolve --- Solve a lower-triangular linear system, Next: igraph_sparsemat_cholsol --- Solve a symmetric linear system via Cholesky decomposition, Prev: igraph_sparsemat_usolve --- Solve an upper-triangular linear system, Up: Decompositions and solving linear systems
7.5.6.6 igraph_sparsemat_utsolve -- Solve a lower-triangular linear system
..........................................................................
int igraph_sparsemat_utsolve(const igraph_sparsemat_t *U,
const igraph_vector_t *b,
igraph_vector_t *res);
This is the same as `igraph_sparsemat_usolve()' (*note
igraph_sparsemat_usolve --- Solve an upper-triangular linear system::),
but U'x=b is solved, where the apostrophe denotes the transpose.
*Arguments:. *
`U':
The input matrix, in column-compressed format.
`b':
The right hand side of the linear system.
`res':
An initialized vector, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_cholsol --- Solve a symmetric linear system via Cholesky decomposition, Next: igraph_sparsemat_lusol --- Solve a linear system via LU decomposition, Prev: igraph_sparsemat_utsolve --- Solve a lower-triangular linear system, Up: Decompositions and solving linear systems
7.5.6.7 igraph_sparsemat_cholsol -- Solve a symmetric linear system via Cholesky decomposition
..............................................................................................
int igraph_sparsemat_cholsol(const igraph_sparsemat_t *A,
const igraph_vector_t *b,
igraph_vector_t *res,
int order);
Solve Ax=b, where A is a symmetric positive definite matrix.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`v':
The right hand side.
`res':
An initialized vector, the result is stored here.
`order':
An integer giving the ordering method to use for the
factorization. Zero is the natural ordering; if it is one, then
the fill-reducing minimum-degree ordering of A+A' is used.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_lusol --- Solve a linear system via LU decomposition, Next: igraph_sparsemat_lu --- LU decomposition of a sparse matrix, Prev: igraph_sparsemat_cholsol --- Solve a symmetric linear system via Cholesky decomposition, Up: Decompositions and solving linear systems
7.5.6.8 igraph_sparsemat_lusol -- Solve a linear system via LU decomposition
............................................................................
int igraph_sparsemat_lusol(const igraph_sparsemat_t *A,
const igraph_vector_t *b,
igraph_vector_t *res,
int order,
igraph_real_t tol);
Solve Ax=b, via LU factorization of A.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`b':
The right hand side of the equation.
`res':
An initialized vector, the result is stored here.
`order':
The ordering method to use, zero means the natural ordering, one
means the fill-reducing minimum-degree ordering of A+A', two means
the ordering of A'*A, after removing the dense rows from A. Three
means the ordering of A'*A.
`tol':
Real number, the tolerance limit to use for the numeric LU
factorization.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_lu --- LU decomposition of a sparse matrix, Next: igraph_sparsemat_qr --- QR decomposition of a sparse matrix, Prev: igraph_sparsemat_lusol --- Solve a linear system via LU decomposition, Up: Decompositions and solving linear systems
7.5.6.9 igraph_sparsemat_lu -- LU decomposition of a sparse matrix
..................................................................
int igraph_sparsemat_lu(const igraph_sparsemat_t *A,
const igraph_sparsemat_symbolic_t *dis,
igraph_sparsemat_numeric_t *din, double tol);
Performs numeric sparse LU decomposition of a matrix.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`dis':
The symbolic analysis for LU decomposition, coming from a call to
the `igraph_sparsemat_symblu()' (*note igraph_sparsemat_symblu ---
Symbolic LU decomposition::) function.
`din':
The numeric decomposition, the result is stored here. It can be
used to solve linear systems with changing right hand side
vectors, by calling `igraph_sparsemat_luresol()' (*note
igraph_sparsemat_luresol --- Solve linear system using a
precomputed LU decomposition::). Once not needed any more, it must
be destroyed by calling `igraph_sparsemat_symbolic_destroy()'
(*note igraph_sparsemat_symbolic_destroy --- Deallocate memory for
a symbolic decomposition::) on it.
`tol':
The tolerance for the numeric LU decomposition.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_qr --- QR decomposition of a sparse matrix, Next: igraph_sparsemat_luresol --- Solve linear system using a precomputed LU decomposition, Prev: igraph_sparsemat_lu --- LU decomposition of a sparse matrix, Up: Decompositions and solving linear systems
7.5.6.10 igraph_sparsemat_qr -- QR decomposition of a sparse matrix
...................................................................
int igraph_sparsemat_qr(const igraph_sparsemat_t *A,
const igraph_sparsemat_symbolic_t *dis,
igraph_sparsemat_numeric_t *din);
Numeric QR decomposition of a sparse matrix.
*Arguments:. *
`A':
The input matrix, in column-compressed format.
`dis':
The result of the symbolic QR analysis, from the function
`igraph_sparsemat_symbqr()' (*note igraph_sparsemat_symbqr ---
Symbolic QR decomposition::).
`din':
The result of the decomposition is stored here, it can be used to
solve many linear systems with the same coefficient matrix and
changing right hand sides, using the `igraph_sparsemat_qrresol()'
(*note igraph_sparsemat_qrresol --- Solve a linear system using a
precomputed QR decomposition::) function. Once not needed any more,
one should call `igraph_sparsemat_numeric_destroy()' (*note
igraph_sparsemat_numeric_destroy --- Deallocate memory for a
numeric decomposition::) on it to free the allocated memory.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_luresol --- Solve linear system using a precomputed LU decomposition, Next: igraph_sparsemat_qrresol --- Solve a linear system using a precomputed QR decomposition, Prev: igraph_sparsemat_qr --- QR decomposition of a sparse matrix, Up: Decompositions and solving linear systems
7.5.6.11 igraph_sparsemat_luresol -- Solve linear system using a precomputed LU decomposition
.............................................................................................
int igraph_sparsemat_luresol(const igraph_sparsemat_symbolic_t *dis,
const igraph_sparsemat_numeric_t *din,
const igraph_vector_t *b,
igraph_vector_t *res);
Uses the LU decomposition of a matrix to solve linear systems.
*Arguments:. *
`dis':
The symbolic analysis of the coefficient matrix, the result of
`igraph_sparsemat_symblu()' (*note igraph_sparsemat_symblu ---
Symbolic LU decomposition::).
`din':
The LU decomposition, the result of a call to
`igraph_sparsemat_lu()' (*note igraph_sparsemat_lu --- LU
decomposition of a sparse matrix::).
`b':
A vector that defines the right hand side of the linear equation
system.
`res':
An initialized vector, the solution of the linear system is stored
here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_qrresol --- Solve a linear system using a precomputed QR decomposition, Next: igraph_sparsemat_symbolic_destroy --- Deallocate memory for a symbolic decomposition, Prev: igraph_sparsemat_luresol --- Solve linear system using a precomputed LU decomposition, Up: Decompositions and solving linear systems
7.5.6.12 igraph_sparsemat_qrresol -- Solve a linear system using a precomputed QR decomposition
...............................................................................................
int igraph_sparsemat_qrresol(const igraph_sparsemat_symbolic_t *dis,
const igraph_sparsemat_numeric_t *din,
const igraph_vector_t *b,
igraph_vector_t *res);
Solves a linear system using a QR decomposition of its coefficient
matrix.
*Arguments:. *
`dis':
Symbolic analysis of the coefficient matrix, the result of
`igraph_sparsemat_symbqr()' (*note igraph_sparsemat_symbqr ---
Symbolic QR decomposition::).
`din':
The QR decomposition of the coefficient matrix, the result of
`igraph_sparsemat_qr()' (*note igraph_sparsemat_qr --- QR
decomposition of a sparse matrix::).
`b':
Vector, giving the right hand side of the linear equation system.
`res':
An initialized vector, the solution is stored here. It is resized
as needed.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_symbolic_destroy --- Deallocate memory for a symbolic decomposition, Next: igraph_sparsemat_numeric_destroy --- Deallocate memory for a numeric decomposition, Prev: igraph_sparsemat_qrresol --- Solve a linear system using a precomputed QR decomposition, Up: Decompositions and solving linear systems
7.5.6.13 igraph_sparsemat_symbolic_destroy -- Deallocate memory for a symbolic decomposition
............................................................................................
void igraph_sparsemat_symbolic_destroy(igraph_sparsemat_symbolic_t *dis);
Frees the memory allocated by `igraph_sparsemat_symbqr()' (*note
igraph_sparsemat_symbqr --- Symbolic QR decomposition::) or
`igraph_sparsemat_symblu()' (*note igraph_sparsemat_symblu --- Symbolic
LU decomposition::).
*Arguments:. *
`dis':
The symbolic analysis.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_sparsemat_numeric_destroy --- Deallocate memory for a numeric decomposition, Prev: igraph_sparsemat_symbolic_destroy --- Deallocate memory for a symbolic decomposition, Up: Decompositions and solving linear systems
7.5.6.14 igraph_sparsemat_numeric_destroy -- Deallocate memory for a numeric decomposition
..........................................................................................
void igraph_sparsemat_numeric_destroy(igraph_sparsemat_numeric_t *din);
Frees the memoty allocated by `igraph_sparsemat_qr()' (*note
igraph_sparsemat_qr --- QR decomposition of a sparse matrix::) or
`igraph_sparsemat_lu()' (*note igraph_sparsemat_lu --- LU decomposition
of a sparse matrix::).
*Arguments:. *
`din':
The LU or QR decomposition.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Eigenvalues and eigenvectors, Next: Conversion to other data types, Prev: Decompositions and solving linear systems, Up: Sparse matrices; another kind
7.5.7 Eigenvalues and eigenvectors
----------------------------------
* Menu:
* igraph_sparsemat_arpack_rssolve --- Eigenvalues and eigenvectors of a symmetric sparse matrix via ARPACK::
* igraph_sparsemat_arpack_rnsolve --- Eigenvalues and eigenvectors of a nonsymmetric sparse matrix via ARPACK::
File: igraph_reference_manual.info, Node: igraph_sparsemat_arpack_rssolve --- Eigenvalues and eigenvectors of a symmetric sparse matrix via ARPACK, Next: igraph_sparsemat_arpack_rnsolve --- Eigenvalues and eigenvectors of a nonsymmetric sparse matrix via ARPACK, Up: Eigenvalues and eigenvectors
7.5.7.1 igraph_sparsemat_arpack_rssolve -- Eigenvalues and eigenvectors of a symmetric sparse matrix via ARPACK
...............................................................................................................
int igraph_sparsemat_arpack_rssolve(const igraph_sparsemat_t *A,
igraph_arpack_options_t *options,
igraph_arpack_storage_t *storage,
igraph_vector_t *values,
igraph_matrix_t *vectors,
igraph_sparsemat_solve_t solvemethod);
*Arguments:. *
`The':
input matrix, must be column-compressed.
`options':
It is passed to `igraph_arpack_rssolve()' (*note
igraph_arpack_rssolve --- ARPACK solver for symmetric matrices::).
See `igraph_arpack_options_t' (*note igraph_arpack_options_t ---
Options for ARPACK::) for the details. If `mode' is 1, then ARPACK
uses regular mode, if `mode' is 3, then shift and invert mode is
used and the `sigma' structure member defines the shift.
`storage':
Storage for ARPACK. See `igraph_arpack_rssolve()' (*note
igraph_arpack_rssolve --- ARPACK solver for symmetric matrices::)
and `igraph_arpack_storage_t' (*note igraph_arpack_storage_t ---
Storage for ARPACK::) for details.
`values':
An initialized vector or a null pointer, the eigenvalues are
stored here.
`vectors':
An initialised matrix, or a null pointer, the eigenvectors are
stored here, in the columns.
`solvemethod':
The method to solve the linear system, if `mode' is 3, i.e. the
shift and invert mode is used. Possible values:
`IGRAPH_SPARSEMAT_SOLVE_LU'
The linear system is solved using LU decomposition.
`IGRAPH_SPARSEMAT_SOLVE_QR'
The linear system is solved using QR decomposition.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_sparsemat_arpack_rnsolve --- Eigenvalues and eigenvectors of a nonsymmetric sparse matrix via ARPACK, Prev: igraph_sparsemat_arpack_rssolve --- Eigenvalues and eigenvectors of a symmetric sparse matrix via ARPACK, Up: Eigenvalues and eigenvectors
7.5.7.2 igraph_sparsemat_arpack_rnsolve -- Eigenvalues and eigenvectors of a nonsymmetric sparse matrix via ARPACK
..................................................................................................................
int igraph_sparsemat_arpack_rnsolve(const igraph_sparsemat_t *A,
igraph_arpack_options_t *options,
igraph_arpack_storage_t *storage,
igraph_matrix_t *values,
igraph_matrix_t *vectors);
Eigenvalues and/or eigenvectors of a nonsymmetric sparse matrix.
*Arguments:. *
`A':
The input matrix, in column-compressed mode.
`options':
ARPACK options, it is passed to `igraph_arpack_rnsolve()' (*note
igraph_arpack_rnsolve --- ARPACK solver for non-symmetric
matrices::). See also `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) for details.
`storage':
Storage for ARPACK, this is passed to `igraph_arpack_rnsolve()'
(*note igraph_arpack_rnsolve --- ARPACK solver for non-symmetric
matrices::). See `igraph_arpack_storage_t' (*note
igraph_arpack_storage_t --- Storage for ARPACK::) for details.
`values':
An initialized matrix, or a null pointer. If not a null pointer,
then the eigenvalues are stored here, the first column is the real
part, the second column is the imaginary part.
`vectors':
An initialized matrix, or a null pointer. If not a null pointer,
then the eigenvectors are stored here, please see
`igraph_arpack_rnsolve()' (*note igraph_arpack_rnsolve --- ARPACK
solver for non-symmetric matrices::) for the format.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: Conversion to other data types, Next: Writing to a file; or to the screen, Prev: Eigenvalues and eigenvectors, Up: Sparse matrices; another kind
7.5.8 Conversion to other data types
------------------------------------
* Menu:
* igraph_sparsemat --- Create an igraph graph from a sparse matrix::
* igraph_get_sparsemat --- Convert an igraph graph to a sparse matrix::
* igraph_matrix_as_sparsemat --- Convert a dense matrix to a sparse matrix::
* igraph_sparsemat_as_matrix --- Convert a sparse matrix to a dense matrix::
File: igraph_reference_manual.info, Node: igraph_sparsemat --- Create an igraph graph from a sparse matrix, Next: igraph_get_sparsemat --- Convert an igraph graph to a sparse matrix, Up: Conversion to other data types
7.5.8.1 igraph_sparsemat -- Create an igraph graph from a sparse matrix
.......................................................................
int igraph_sparsemat(igraph_t *graph, const igraph_sparsemat_t *A,
igraph_bool_t directed);
One edge is created for each non-zero entry in the matrix. If you
have a symmetric matrix, and want to create an undirected graph, then
delete the entries in the upper diagonal first, or call
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::) on the result graph to eliminate the
multiple edges.
*Arguments:. *
`graph':
Pointer to an uninitialized igraph_t object, the graphs is stored
here.
`A':
The input matrix, in triplet or column-compressed format.
`directed':
Boolean scalar, whether to create a directed graph.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_get_sparsemat --- Convert an igraph graph to a sparse matrix, Next: igraph_matrix_as_sparsemat --- Convert a dense matrix to a sparse matrix, Prev: igraph_sparsemat --- Create an igraph graph from a sparse matrix, Up: Conversion to other data types
7.5.8.2 igraph_get_sparsemat -- Convert an igraph graph to a sparse matrix
..........................................................................
int igraph_get_sparsemat(const igraph_t *graph, igraph_sparsemat_t *res);
If the graph is undirected, then a symmetric matrix is created.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an uninitialized sparse matrix. The result will be
stored here.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_matrix_as_sparsemat --- Convert a dense matrix to a sparse matrix, Next: igraph_sparsemat_as_matrix --- Convert a sparse matrix to a dense matrix, Prev: igraph_get_sparsemat --- Convert an igraph graph to a sparse matrix, Up: Conversion to other data types
7.5.8.3 igraph_matrix_as_sparsemat -- Convert a dense matrix to a sparse matrix
...............................................................................
int igraph_matrix_as_sparsemat(igraph_sparsemat_t *res,
const igraph_matrix_t *mat,
igraph_real_t tol);
*Arguments:. *
`res':
An uninitialized sparse matrix, the result is stored here.
`mat':
The dense input matrix.
`tol':
Real scalar, the tolerance. Values closer than `tol' to zero are
considered as zero, and will not be included in the sparse matrix.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the dense matrix.
File: igraph_reference_manual.info, Node: igraph_sparsemat_as_matrix --- Convert a sparse matrix to a dense matrix, Prev: igraph_matrix_as_sparsemat --- Convert a dense matrix to a sparse matrix, Up: Conversion to other data types
7.5.8.4 igraph_sparsemat_as_matrix -- Convert a sparse matrix to a dense matrix
...............................................................................
int igraph_sparsemat_as_matrix(igraph_matrix_t *res,
const igraph_sparsemat_t *spmat);
*Arguments:. *
`res':
Pointer to an initialized matrix, the result is stored here. It
will be resized to the required size.
`spmat':
The input sparse matrix, in triplet or column-compressed format.
*Returns:. *
`'
Error code.
Time complexity: O(mn), the number of elements in the dense matrix.
File: igraph_reference_manual.info, Node: Writing to a file; or to the screen, Prev: Conversion to other data types, Up: Sparse matrices; another kind
7.5.9 Writing to a file, or to the screen
-----------------------------------------
* Menu:
* igraph_sparsemat_print --- Print a sparse matrix to a file::
File: igraph_reference_manual.info, Node: igraph_sparsemat_print --- Print a sparse matrix to a file, Up: Writing to a file; or to the screen
7.5.9.1 igraph_sparsemat_print -- Print a sparse matrix to a file
.................................................................
int igraph_sparsemat_print(const igraph_sparsemat_t *A,
FILE *outstream);
Only the non-zero entries are printed. This function serves more as
a debugging utility, as currently there is no function that could read
back the printed matrix from the file.
*Arguments:. *
`A':
The input matrix, triplet or column-compressed format.
`outstream':
The stream to print it to.
*Returns:. *
`'
Error code.
Time complexity: O(nz) for triplet matrices, O(n+nz) for
column-compressed matrices. nz is the number of non-zero elements, n is
the number columns in the matrix.
File: igraph_reference_manual.info, Node: Stacks, Next: Double-ended queues, Prev: Sparse matrices; another kind, Up: Data structure library; vector; matrix; other data types
7.6 Stacks
==========
* Menu:
* igraph_stack_init --- Initializes a stack.: igraph_stack_init --- Initializes a stack_.
* igraph_stack_destroy --- Destroys a stack object.: igraph_stack_destroy --- Destroys a stack object_.
* igraph_stack_reserve --- Reserve memory.: igraph_stack_reserve --- Reserve memory_.
* igraph_stack_empty --- Decides whether a stack object is empty.: igraph_stack_empty --- Decides whether a stack object is empty_.
* igraph_stack_size --- Returns the number of elements in a stack.: igraph_stack_size --- Returns the number of elements in a stack_.
* igraph_stack_clear --- Removes all elements from a stack.: igraph_stack_clear --- Removes all elements from a stack_.
* igraph_stack_push --- Places an element on the top of a stack.: igraph_stack_push --- Places an element on the top of a stack_.
* igraph_stack_pop --- Removes and returns an element from the top of a stack.: igraph_stack_pop --- Removes and returns an element from the top of a stack_.
* igraph_stack_top --- Query top element.: igraph_stack_top --- Query top element_.
File: igraph_reference_manual.info, Node: igraph_stack_init --- Initializes a stack_, Next: igraph_stack_destroy --- Destroys a stack object_, Up: Stacks
7.6.1 igraph_stack_init -- Initializes a stack.
-----------------------------------------------
int igraph_stack_init (igraph_stack_t* s, long int size);
The initialized stack is always empty.
*Arguments:. *
`s':
Pointer to an uninitialized stack.
`size':
The number of elements to allocate memory for.
*Returns:. *
`'
Error code.
Time complexity: O(`size').
File: igraph_reference_manual.info, Node: igraph_stack_destroy --- Destroys a stack object_, Next: igraph_stack_reserve --- Reserve memory_, Prev: igraph_stack_init --- Initializes a stack_, Up: Stacks
7.6.2 igraph_stack_destroy -- Destroys a stack object.
------------------------------------------------------
void igraph_stack_destroy (igraph_stack_t* s);
Deallocate the memory used for a stack. It is possible to
reinitialize a destroyed stack again by `igraph_stack_init()' (*note
igraph_stack_init --- Initializes a stack_::).
*Arguments:. *
`s':
The stack to destroy.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_stack_reserve --- Reserve memory_, Next: igraph_stack_empty --- Decides whether a stack object is empty_, Prev: igraph_stack_destroy --- Destroys a stack object_, Up: Stacks
7.6.3 igraph_stack_reserve -- Reserve memory.
---------------------------------------------
int igraph_stack_reserve (igraph_stack_t* s, long int size);
Reverse memory for future use. The actual size of the stack is
unchanged.
*Arguments:. *
`s':
The stack object.
`size':
The number of elements to reserve memory for. If it is not bigger
than the current size then nothing happens.
*Returns:. *
`'
Error code.
Time complexity: should be around O(n), the new allocated size of
the stack.
File: igraph_reference_manual.info, Node: igraph_stack_empty --- Decides whether a stack object is empty_, Next: igraph_stack_size --- Returns the number of elements in a stack_, Prev: igraph_stack_reserve --- Reserve memory_, Up: Stacks
7.6.4 igraph_stack_empty -- Decides whether a stack object is empty.
--------------------------------------------------------------------
igraph_bool_t igraph_stack_empty (igraph_stack_t* s);
*Arguments:. *
`s':
The stack object.
*Returns:. *
`'
Boolean, `TRUE' if the stack is empty, `FALSE' otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_stack_size --- Returns the number of elements in a stack_, Next: igraph_stack_clear --- Removes all elements from a stack_, Prev: igraph_stack_empty --- Decides whether a stack object is empty_, Up: Stacks
7.6.5 igraph_stack_size -- Returns the number of elements in a stack.
---------------------------------------------------------------------
long int igraph_stack_size (const igraph_stack_t* s);
*Arguments:. *
`s':
The stack object.
*Returns:. *
`'
The number of elements in the stack.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_stack_clear --- Removes all elements from a stack_, Next: igraph_stack_push --- Places an element on the top of a stack_, Prev: igraph_stack_size --- Returns the number of elements in a stack_, Up: Stacks
7.6.6 igraph_stack_clear -- Removes all elements from a stack.
--------------------------------------------------------------
void igraph_stack_clear (igraph_stack_t* s);
*Arguments:. *
`s':
The stack object.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_stack_push --- Places an element on the top of a stack_, Next: igraph_stack_pop --- Removes and returns an element from the top of a stack_, Prev: igraph_stack_clear --- Removes all elements from a stack_, Up: Stacks
7.6.7 igraph_stack_push -- Places an element on the top of a stack.
-------------------------------------------------------------------
int igraph_stack_push(igraph_stack_t* s, igraph_real_t elem);
The capacity of the stack is increased, if needed.
*Arguments:. *
`s':
The stack object.
`elem':
The element to push.
*Returns:. *
`'
Error code.
Time complexity: O(1) is no reallocation is needed, O(n) otherwise,
but it is ensured that n push operations are performed in O(n) time.
File: igraph_reference_manual.info, Node: igraph_stack_pop --- Removes and returns an element from the top of a stack_, Next: igraph_stack_top --- Query top element_, Prev: igraph_stack_push --- Places an element on the top of a stack_, Up: Stacks
7.6.8 igraph_stack_pop -- Removes and returns an element from the top of a stack.
---------------------------------------------------------------------------------
igraph_real_t igraph_stack_pop (igraph_stack_t* s);
The stack must contain at least one element, call
`igraph_stack_empty()' (*note igraph_stack_empty --- Decides whether a
stack object is empty_::) to make sure of this.
*Arguments:. *
`s':
The stack object.
*Returns:. *
`'
The removed top element.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_stack_top --- Query top element_, Prev: igraph_stack_pop --- Removes and returns an element from the top of a stack_, Up: Stacks
7.6.9 igraph_stack_top -- Query top element.
--------------------------------------------
igraph_real_t igraph_stack_top (const igraph_stack_t* s);
Returns the top element of the stack, without removing it. The
stack must be non-empty.
*Arguments:. *
`s':
The stack.
*Returns:. *
`'
The top element.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Double-ended queues, Next: Maximum and minimum heaps, Prev: Stacks, Up: Data structure library; vector; matrix; other data types
7.7 Double-ended queues
=======================
This is the classic data type of the double ended queue. Most of the
time it is used if a First-In-First-Out (FIFO) behavior is needed. See
the operations below.
* File examples/simple/dqueue.c*
* Menu:
* igraph_dqueue_init --- Initialize a double ended queue (deque).: igraph_dqueue_init --- Initialize a double ended queue [deque]_.
* igraph_dqueue_destroy --- Destroy a double ended queue.: igraph_dqueue_destroy --- Destroy a double ended queue_.
* igraph_dqueue_empty --- Decide whether the queue is empty.: igraph_dqueue_empty --- Decide whether the queue is empty_.
* igraph_dqueue_full --- Check whether the queue is full.: igraph_dqueue_full --- Check whether the queue is full_.
* igraph_dqueue_clear --- Remove all elements from the queue.: igraph_dqueue_clear --- Remove all elements from the queue_.
* igraph_dqueue_size --- Number of elements in the queue.: igraph_dqueue_size --- Number of elements in the queue_.
* igraph_dqueue_head --- Head of the queue.: igraph_dqueue_head --- Head of the queue_.
* igraph_dqueue_back --- Tail of the queue.: igraph_dqueue_back --- Tail of the queue_.
* igraph_dqueue_pop --- Remove the head.: igraph_dqueue_pop --- Remove the head_.
* igraph_dqueue_pop_back --- Remove the tail::
* igraph_dqueue_push --- Appends an element.: igraph_dqueue_push --- Appends an element_.
File: igraph_reference_manual.info, Node: igraph_dqueue_init --- Initialize a double ended queue [deque]_, Next: igraph_dqueue_destroy --- Destroy a double ended queue_, Up: Double-ended queues
7.7.1 igraph_dqueue_init -- Initialize a double ended queue (deque).
--------------------------------------------------------------------
int igraph_dqueue_init (igraph_dqueue_t* q, long int size);
The queue will be always empty.
*Arguments:. *
`q':
Pointer to an uninitialized deque.
`size':
How many elements to allocate memory for.
*Returns:. *
`'
Error code.
Time complexity: O(`size').
File: igraph_reference_manual.info, Node: igraph_dqueue_destroy --- Destroy a double ended queue_, Next: igraph_dqueue_empty --- Decide whether the queue is empty_, Prev: igraph_dqueue_init --- Initialize a double ended queue [deque]_, Up: Double-ended queues
7.7.2 igraph_dqueue_destroy -- Destroy a double ended queue.
------------------------------------------------------------
void igraph_dqueue_destroy (igraph_dqueue_t* q);
*Arguments:. *
`q':
The queue to destroy
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_empty --- Decide whether the queue is empty_, Next: igraph_dqueue_full --- Check whether the queue is full_, Prev: igraph_dqueue_destroy --- Destroy a double ended queue_, Up: Double-ended queues
7.7.3 igraph_dqueue_empty -- Decide whether the queue is empty.
---------------------------------------------------------------
igraph_bool_t igraph_dqueue_empty (const igraph_dqueue_t* q);
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
Boolean, `TRUE' if `q' contains at least one element, `FALSE'
otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_full --- Check whether the queue is full_, Next: igraph_dqueue_clear --- Remove all elements from the queue_, Prev: igraph_dqueue_empty --- Decide whether the queue is empty_, Up: Double-ended queues
7.7.4 igraph_dqueue_full -- Check whether the queue is full.
------------------------------------------------------------
igraph_bool_t igraph_dqueue_full (igraph_dqueue_t* q);
If a queue is full the next igraph_dqueue_push() operation will
allocate more memory.
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
`TRUE' if `q' is full, `FALSE' otherwise.
Time complecity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_clear --- Remove all elements from the queue_, Next: igraph_dqueue_size --- Number of elements in the queue_, Prev: igraph_dqueue_full --- Check whether the queue is full_, Up: Double-ended queues
7.7.5 igraph_dqueue_clear -- Remove all elements from the queue.
----------------------------------------------------------------
void igraph_dqueue_clear (igraph_dqueue_t* q);
*Arguments:. *
`q':
The queue
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_size --- Number of elements in the queue_, Next: igraph_dqueue_head --- Head of the queue_, Prev: igraph_dqueue_clear --- Remove all elements from the queue_, Up: Double-ended queues
7.7.6 igraph_dqueue_size -- Number of elements in the queue.
------------------------------------------------------------
long int igraph_dqueue_size (const igraph_dqueue_t* q);
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
Integer, the number of elements currently in the queue.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_head --- Head of the queue_, Next: igraph_dqueue_back --- Tail of the queue_, Prev: igraph_dqueue_size --- Number of elements in the queue_, Up: Double-ended queues
7.7.7 igraph_dqueue_head -- Head of the queue.
----------------------------------------------
igraph_real_t igraph_dqueue_head (const igraph_dqueue_t* q);
The queue must contain at least one element.
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
The first element in the queue.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_back --- Tail of the queue_, Next: igraph_dqueue_pop --- Remove the head_, Prev: igraph_dqueue_head --- Head of the queue_, Up: Double-ended queues
7.7.8 igraph_dqueue_back -- Tail of the queue.
----------------------------------------------
igraph_real_t igraph_dqueue_back (const igraph_dqueue_t* q);
The queue must contain at least one element.
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
The last element in the queue.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_pop --- Remove the head_, Next: igraph_dqueue_pop_back --- Remove the tail, Prev: igraph_dqueue_back --- Tail of the queue_, Up: Double-ended queues
7.7.9 igraph_dqueue_pop -- Remove the head.
-------------------------------------------
igraph_real_t igraph_dqueue_pop (igraph_dqueue_t* q);
Removes and returns the first element in the queue. The queue must
be non-empty.
*Arguments:. *
`q':
The input queue.
*Returns:. *
`'
The first element in the queue.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_pop_back --- Remove the tail, Next: igraph_dqueue_push --- Appends an element_, Prev: igraph_dqueue_pop --- Remove the head_, Up: Double-ended queues
7.7.10 igraph_dqueue_pop_back -- Remove the tail
------------------------------------------------
igraph_real_t igraph_dqueue_pop_back (igraph_dqueue_t* q);
Removes and returns the last element in the queue. The queue must be
non-empty.
*Arguments:. *
`q':
The queue.
*Returns:. *
`'
The last element in the queue.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_dqueue_push --- Appends an element_, Prev: igraph_dqueue_pop_back --- Remove the tail, Up: Double-ended queues
7.7.11 igraph_dqueue_push -- Appends an element.
------------------------------------------------
int igraph_dqueue_push (igraph_dqueue_t* q, igraph_real_t elem);
Append an element to the end of the queue.
*Arguments:. *
`q':
The queue.
`elem':
The element to append.
*Returns:. *
`'
Error code.
Time complexity: O(1) if no memory allocation is needed, O(n), the
number of elements in the queue otherwise. But not that by allocating
always twice as much memory as the current size of the queue we ensure
that n push operations can always be done in at most O(n) time.
(Assuming memory allocation is at most linear.)
File: igraph_reference_manual.info, Node: Maximum and minimum heaps, Next: String vectors, Prev: Double-ended queues, Up: Data structure library; vector; matrix; other data types
7.8 Maximum and minimum heaps
=============================
* Menu:
* igraph_heap_init --- Initializes an empty heap object.: igraph_heap_init --- Initializes an empty heap object_.
* igraph_heap_init_array --- Build a heap from an array.: igraph_heap_init_array --- Build a heap from an array_.
* igraph_heap_destroy --- Destroys an initialized heap object.: igraph_heap_destroy --- Destroys an initialized heap object_.
* igraph_heap_empty --- Decides whether a heap object is empty.: igraph_heap_empty --- Decides whether a heap object is empty_.
* igraph_heap_push --- Add an element.: igraph_heap_push --- Add an element_.
* igraph_heap_top --- Top element.: igraph_heap_top --- Top element_.
* igraph_heap_delete_top --- Return and removes the top element::
* igraph_heap_size --- Number of elements::
* igraph_heap_reserve --- Allocate more memory::
File: igraph_reference_manual.info, Node: igraph_heap_init --- Initializes an empty heap object_, Next: igraph_heap_init_array --- Build a heap from an array_, Up: Maximum and minimum heaps
7.8.1 igraph_heap_init -- Initializes an empty heap object.
-----------------------------------------------------------
int igraph_heap_init(igraph_heap_t* h, long int alloc_size);
Creates an empty heap, but allocates size for some elements.
*Arguments:. *
`h':
Pointer to an uninitialized heap object.
`alloc_size':
Number of elements to allocate memory for.
*Returns:. *
`'
Error code.
Time complexity: O(`alloc_size'), assuming memory allocation is a
linear operation.
File: igraph_reference_manual.info, Node: igraph_heap_init_array --- Build a heap from an array_, Next: igraph_heap_destroy --- Destroys an initialized heap object_, Prev: igraph_heap_init --- Initializes an empty heap object_, Up: Maximum and minimum heaps
7.8.2 igraph_heap_init_array -- Build a heap from an array.
-----------------------------------------------------------
int igraph_heap_init_array(igraph_heap_t *h, igraph_real_t* data, long int len);
Initializes a heap object from an array, the heap is also built of
course (constructor).
*Arguments:. *
`h':
Pointer to an uninitialized heap object.
`data':
Pointer to an array of base data type.
`len':
The length of the array at `data'.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of elements in the heap.
File: igraph_reference_manual.info, Node: igraph_heap_destroy --- Destroys an initialized heap object_, Next: igraph_heap_empty --- Decides whether a heap object is empty_, Prev: igraph_heap_init_array --- Build a heap from an array_, Up: Maximum and minimum heaps
7.8.3 igraph_heap_destroy -- Destroys an initialized heap object.
-----------------------------------------------------------------
void igraph_heap_destroy(igraph_heap_t* h);
*Arguments:. *
`h':
The heap object.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_heap_empty --- Decides whether a heap object is empty_, Next: igraph_heap_push --- Add an element_, Prev: igraph_heap_destroy --- Destroys an initialized heap object_, Up: Maximum and minimum heaps
7.8.4 igraph_heap_empty -- Decides whether a heap object is empty.
------------------------------------------------------------------
igraph_bool_t igraph_heap_empty(igraph_heap_t* h);
*Arguments:. *
`h':
The heap object.
*Returns:. *
`'
`TRUE' if the heap is empty, `FALSE' otherwise.
TIme complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_heap_push --- Add an element_, Next: igraph_heap_top --- Top element_, Prev: igraph_heap_empty --- Decides whether a heap object is empty_, Up: Maximum and minimum heaps
7.8.5 igraph_heap_push -- Add an element.
-----------------------------------------
int igraph_heap_push(igraph_heap_t* h, igraph_real_t elem);
Adds an element to the heap.
*Arguments:. *
`h':
The heap object.
`elem':
The element to add.
*Returns:. *
`'
Error code.
Time complexity: O(log n), n is the number of elements in the heap
if no reallocation is needed, O(n) otherwise. It is ensured that n push
operations are performed in O(n log n) time.
File: igraph_reference_manual.info, Node: igraph_heap_top --- Top element_, Next: igraph_heap_delete_top --- Return and removes the top element, Prev: igraph_heap_push --- Add an element_, Up: Maximum and minimum heaps
7.8.6 igraph_heap_top -- Top element.
-------------------------------------
igraph_real_t igraph_heap_top(igraph_heap_t* h);
For maximum heaps this is the largest, for minimum heaps the
smallest element of the heap.
*Arguments:. *
`h':
The heap object.
*Returns:. *
`'
The top element.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_heap_delete_top --- Return and removes the top element, Next: igraph_heap_size --- Number of elements, Prev: igraph_heap_top --- Top element_, Up: Maximum and minimum heaps
7.8.7 igraph_heap_delete_top -- Return and removes the top element
------------------------------------------------------------------
igraph_real_t igraph_heap_delete_top(igraph_heap_t* h);
Removes and returns the top element of the heap. For maximum heaps
this is the largest, for minimum heaps the smallest element.
*Arguments:. *
`h':
The heap object.
*Returns:. *
`'
The top element.
Time complexity: O(log n), n is the number of elements in the heap.
File: igraph_reference_manual.info, Node: igraph_heap_size --- Number of elements, Next: igraph_heap_reserve --- Allocate more memory, Prev: igraph_heap_delete_top --- Return and removes the top element, Up: Maximum and minimum heaps
7.8.8 igraph_heap_size -- Number of elements
--------------------------------------------
long int igraph_heap_size(igraph_heap_t* h);
Gives the number of elements in a heap.
*Arguments:. *
`h':
The heap object.
*Returns:. *
`'
The number of elements in the heap.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_heap_reserve --- Allocate more memory, Prev: igraph_heap_size --- Number of elements, Up: Maximum and minimum heaps
7.8.9 igraph_heap_reserve -- Allocate more memory
-------------------------------------------------
int igraph_heap_reserve(igraph_heap_t* h, long int size);
Allocates memory for future use. The size of the heap is unchanged.
If the heap is larger than the `size' parameter then nothing happens.
*Arguments:. *
`h':
The heap object.
`size':
The number of elements to allocate memory for.
*Returns:. *
`'
Error code.
Time complexity: O(`size') if `size' is larger than the current
number of elements. O(1) otherwise.
File: igraph_reference_manual.info, Node: String vectors, Next: Adjacency lists, Prev: Maximum and minimum heaps, Up: Data structure library; vector; matrix; other data types
7.9 String vectors
==================
The `igraph_strvector_t' type is a vector of strings. The current
implementation is very simple and not too efficient. It works fine for
not too many strings, e.g. the list of attribute names is returned in a
string vector by `igraph_cattribute_list()' (*note
igraph_cattribute_list --- List all attributes::). Do not expect great
performance from this type.
* File examples/simple/igraph_strvector.c*
* Menu:
* igraph_strvector_init --- Initialize::
* igraph_strvector_copy --- Initialization by copying.: igraph_strvector_copy --- Initialization by copying_.
* igraph_strvector_destroy --- Free allocated memory::
* STR --- Indexing string vectors::
* igraph_strvector_get --- Indexing::
* igraph_strvector_set --- Set an element::
* igraph_strvector_set2 --- Sets an element::
* igraph_strvector_remove --- Removes a single element from a string vector.: igraph_strvector_remove --- Removes a single element from a string vector_.
* igraph_strvector_append --- Concatenate two string vectors.: igraph_strvector_append --- Concatenate two string vectors_.
* igraph_strvector_clear --- Remove all elements::
* igraph_strvector_resize --- Resize::
* igraph_strvector_size --- Gives the size of a string vector.: igraph_strvector_size --- Gives the size of a string vector_.
* igraph_strvector_add --- Adds an element to the back of a string vector.: igraph_strvector_add --- Adds an element to the back of a string vector_.
File: igraph_reference_manual.info, Node: igraph_strvector_init --- Initialize, Next: igraph_strvector_copy --- Initialization by copying_, Up: String vectors
7.9.1 igraph_strvector_init -- Initialize
-----------------------------------------
int igraph_strvector_init(igraph_strvector_t *sv, long int len);
Reserves memory for the string vector, a string vector must be first
initialized before calling other functions on it. All elements of the
string vector are set to the empty string.
*Arguments:. *
`sv':
Pointer to an initialized string vector.
`len':
The (initial) length of the string vector.
*Returns:. *
`'
Error code.
Time complexity: O(`len').
File: igraph_reference_manual.info, Node: igraph_strvector_copy --- Initialization by copying_, Next: igraph_strvector_destroy --- Free allocated memory, Prev: igraph_strvector_init --- Initialize, Up: String vectors
7.9.2 igraph_strvector_copy -- Initialization by copying.
---------------------------------------------------------
int igraph_strvector_copy(igraph_strvector_t *to,
const igraph_strvector_t *from);
Initializes a string vector by copying another string vector.
*Arguments:. *
`to':
Pointer to an uninitialized string vector.
`from':
The other string vector, to be copied.
*Returns:. *
`'
Error code.
Time complexity: O(l), the total length of the strings in `from'.
File: igraph_reference_manual.info, Node: igraph_strvector_destroy --- Free allocated memory, Next: STR --- Indexing string vectors, Prev: igraph_strvector_copy --- Initialization by copying_, Up: String vectors
7.9.3 igraph_strvector_destroy -- Free allocated memory
-------------------------------------------------------
void igraph_strvector_destroy(igraph_strvector_t *sv);
Destroy a string vector. It may be reinitialized with
`igraph_strvector_init()' (*note igraph_strvector_init ---
Initialize::) later.
*Arguments:. *
`sv':
The string vector.
Time complexity: O(l), the total length of the strings, maybe less
depending on the memory manager.
File: igraph_reference_manual.info, Node: STR --- Indexing string vectors, Next: igraph_strvector_get --- Indexing, Prev: igraph_strvector_destroy --- Free allocated memory, Up: String vectors
7.9.4 STR -- Indexing string vectors
------------------------------------
#define STR(sv,i)
This is a macro which allows to query the elements of a string
vector in simpler way than `igraph_strvector_get()' (*note
igraph_strvector_get --- Indexing::). Note this macro cannot be used to
set an element, for that use `igraph_strvector_set()' (*note
igraph_strvector_set --- Set an element::).
*Arguments:. *
`sv':
The string vector
`i':
The the index of the element.
*Returns:. *
`'
The element at position `i'.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_strvector_get --- Indexing, Next: igraph_strvector_set --- Set an element, Prev: STR --- Indexing string vectors, Up: String vectors
7.9.5 igraph_strvector_get -- Indexing
--------------------------------------
void igraph_strvector_get(const igraph_strvector_t *sv, long int idx,
char **value);
Query an element of a string vector. See also the `STR' (*note STR
--- Indexing string vectors::) macro for an easier way.
*Arguments:. *
`sv':
The input string vector.
`idx':
The index of the element to query.
`Pointer':
to a `char*', the address of the string is stored here.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_strvector_set --- Set an element, Next: igraph_strvector_set2 --- Sets an element, Prev: igraph_strvector_get --- Indexing, Up: String vectors
7.9.6 igraph_strvector_set -- Set an element
--------------------------------------------
int igraph_strvector_set(igraph_strvector_t *sv, long int idx,
const char *value);
The provided `value' is copied into the `idx' position in the string
vector.
*Arguments:. *
`sv':
The string vector.
`idx':
The position to set.
`value':
The new value.
*Returns:. *
`'
Error code.
Time complexity: O(l), the length of the new string. Maybe more,
depending on the memory management, if reallocation is needed.
File: igraph_reference_manual.info, Node: igraph_strvector_set2 --- Sets an element, Next: igraph_strvector_remove --- Removes a single element from a string vector_, Prev: igraph_strvector_set --- Set an element, Up: String vectors
7.9.7 igraph_strvector_set2 -- Sets an element
----------------------------------------------
int igraph_strvector_set2(igraph_strvector_t *sv, long int idx,
const char *value, int len);
This is almost the same as `igraph_strvector_set' (*note
igraph_strvector_set --- Set an element::), but the new value is not a
zero terminated string, but its length is given.
*Arguments:. *
`sv':
The string vector.
`idx':
The position to set.
`value':
The new value.
`len':
The length of the new value.
*Returns:. *
`'
Error code.
Time complexity: O(l), the length of the new string. Maybe more,
depending on the memory management, if reallocation is needed.
File: igraph_reference_manual.info, Node: igraph_strvector_remove --- Removes a single element from a string vector_, Next: igraph_strvector_append --- Concatenate two string vectors_, Prev: igraph_strvector_set2 --- Sets an element, Up: String vectors
7.9.8 igraph_strvector_remove -- Removes a single element from a string vector.
-------------------------------------------------------------------------------
void igraph_strvector_remove(igraph_strvector_t *v, long int elem);
The string will be one shorter.
*Arguments:. *
`The':
string vector.
`elem':
The index of the element to remove.
Time complexity: O(n), the length of the string.
File: igraph_reference_manual.info, Node: igraph_strvector_append --- Concatenate two string vectors_, Next: igraph_strvector_clear --- Remove all elements, Prev: igraph_strvector_remove --- Removes a single element from a string vector_, Up: String vectors
7.9.9 igraph_strvector_append -- Concatenate two string vectors.
----------------------------------------------------------------
int igraph_strvector_append(igraph_strvector_t *to,
const igraph_strvector_t *from);
*Arguments:. *
`to':
The first string vector, the result is stored here.
`from':
The second string vector, it is kept unchanged.
*Returns:. *
`'
Error code.
Time complexity: O(n+l2), n is the number of strings in the new
string vector, l2 is the total length of strings in the `from' string
vector.
File: igraph_reference_manual.info, Node: igraph_strvector_clear --- Remove all elements, Next: igraph_strvector_resize --- Resize, Prev: igraph_strvector_append --- Concatenate two string vectors_, Up: String vectors
7.9.10 igraph_strvector_clear -- Remove all elements
----------------------------------------------------
void igraph_strvector_clear(igraph_strvector_t *sv);
After this operation the string vector will be empty.
*Arguments:. *
`sv':
The string vector.
Time complexity: O(l), the total length of strings, maybe less,
depending on the memory manager.
File: igraph_reference_manual.info, Node: igraph_strvector_resize --- Resize, Next: igraph_strvector_size --- Gives the size of a string vector_, Prev: igraph_strvector_clear --- Remove all elements, Up: String vectors
7.9.11 igraph_strvector_resize -- Resize
----------------------------------------
int igraph_strvector_resize(igraph_strvector_t* v, long int newsize);
If the new size is bigger then empty strings are added, if it is
smaller then the unneeded elements are removed.
*Arguments:. *
`v':
The string vector.
`newsize':
The new size.
*Returns:. *
`'
Error code.
Time complexity: O(n), the number of strings if the vector is made
bigger, O(l), the total length of the deleted strings if it is made
smaller, maybe less, depending on memory management.
File: igraph_reference_manual.info, Node: igraph_strvector_size --- Gives the size of a string vector_, Next: igraph_strvector_add --- Adds an element to the back of a string vector_, Prev: igraph_strvector_resize --- Resize, Up: String vectors
7.9.12 igraph_strvector_size -- Gives the size of a string vector.
------------------------------------------------------------------
long int igraph_strvector_size(const igraph_strvector_t *sv);
*Arguments:. *
`sv':
The string vector.
*Returns:. *
`'
The length of the string vector.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_strvector_add --- Adds an element to the back of a string vector_, Prev: igraph_strvector_size --- Gives the size of a string vector_, Up: String vectors
7.9.13 igraph_strvector_add -- Adds an element to the back of a string vector.
------------------------------------------------------------------------------
int igraph_strvector_add(igraph_strvector_t *v, const char *value);
*Arguments:. *
`v':
The string vector.
`value':
The string to add, it will be copied.
*Returns:. *
`'
Error code.
Time complexity: O(n+l), n is the total number of strings, l is the
length of the new string.
File: igraph_reference_manual.info, Node: Adjacency lists, Prev: String vectors, Up: Data structure library; vector; matrix; other data types
7.10 Adjacency lists
====================
Sometimes it is easier to work with a graph which is in adjacency list
format: a list of vectors; each vector contains the neighbor vertices
or incident edges of a given vertex. Typically, this representation is
good if we need to iterate over the neighbors of all vertices many
times. E.g. when finding the shortest paths between every pairs of
vertices or calculating closeness centrality for all the vertices.
The `igraph_adjlist_t' stores the adjacency lists of a graph. After
creation it is independent of the original graph, it can be modified
freely with the usual vector operations, the graph is not affected.
E.g. the adjacency list can be used to rewire the edges of a graph
efficiently. If one used the straightforward `igraph_delete_edges()'
(*note igraph_delete_edges --- Removes edges from a graph_::) and
`igraph_add_edges()' (*note igraph_add_edges --- Adds edges to a graph
object_::) combination for this that needs O(|V|+|E|) time for every
single deletion and insertion operation, it is thus very slow if many
edges are rewired. Extracting the graph into an adjacency list, do all
the rewiring operations on the vectors of the adjacency list and then
creating a new graph needs (depending on how exactly the rewiring is
done) typically O(|V|+|E|) time for the whole rewiring process.
Lazy adjacency lists are a bit different. When creating a lazy
adjacency list, the neighbors of the vertices are not queried, only
some memory is allocated for the vectors. When
`igraph_lazy_adjlist_get()' (*note igraph_lazy_adjlist_get --- Query
neighbor vertices::) is called for vertex v the first time, the
neighbors of v are queried and stored in a vector of the adjacency
list, so they don't need to be queried again. Lazy adjacency lists are
handy if you have an at least linear operation (because initialization
is generally linear in terms of number of vertices), but you don't know
how many vertices you will visit during the computation.
* File examples/simple/adjlist.c*
* Menu:
* Adjacent vertices::
* Incident edges::
* Lazy adjacency list for vertices::
* Lazy incidence list for edges::
* Deprecated functions: Deprecated functions <1>.
File: igraph_reference_manual.info, Node: Adjacent vertices, Next: Incident edges, Up: Adjacency lists
7.10.1 Adjacent vertices
------------------------
* Menu:
* igraph_adjlist_init --- Initialize an adjacency list of vertices from a given graph::
* igraph_adjlist_init_empty --- Initialize an empty adjacency list::
* igraph_adjlist_init_complementer --- Adjacency lists for the complementer graph::
* igraph_adjlist_destroy --- Deallocate memory::
* igraph_adjlist_get --- Query a vector in an adjlist::
* igraph_adjlist_clear --- Removes all edges from an adjacency list.: igraph_adjlist_clear --- Removes all edges from an adjacency list_.
* igraph_adjlist_sort --- Sort each vector in an adjacency list.: igraph_adjlist_sort --- Sort each vector in an adjacency list_.
* igraph_adjlist_simplify --- Simplify::
File: igraph_reference_manual.info, Node: igraph_adjlist_init --- Initialize an adjacency list of vertices from a given graph, Next: igraph_adjlist_init_empty --- Initialize an empty adjacency list, Up: Adjacent vertices
7.10.1.1 igraph_adjlist_init -- Initialize an adjacency list of vertices from a given graph
...........................................................................................
int igraph_adjlist_init(const igraph_t *graph, igraph_adjlist_t *al,
igraph_neimode_t mode);
Create a list of vectors containing the neighbors of all vertices in
a graph. The adjacency list is independent of the graph after creation,
e.g. the graph can be destroyed and modified, the adjacency list
contains the state of the graph at the time of its initialization.
*Arguments:. *
`graph':
The input graph.
`al':
Pointer to an uninitialized `igraph_adjlist_t' object.
`mode':
Constant specifying whether outgoing (` IGRAPH_OUT' ), incoming (`
IGRAPH_IN' ), or both (` IGRAPH_ALL' ) types of neighbors to
include in the adjacency list. It is ignored for undirected
networks.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
File: igraph_reference_manual.info, Node: igraph_adjlist_init_empty --- Initialize an empty adjacency list, Next: igraph_adjlist_init_complementer --- Adjacency lists for the complementer graph, Prev: igraph_adjlist_init --- Initialize an adjacency list of vertices from a given graph, Up: Adjacent vertices
7.10.1.2 igraph_adjlist_init_empty -- Initialize an empty adjacency list
........................................................................
int igraph_adjlist_init_empty(igraph_adjlist_t *al, igraph_integer_t no_of_nodes);
Creates a list of vectors, one for each vertex. This is useful when
you are _constructing_ a graph using an adjacency list representation as
it does not require your graph to exist yet.
*Arguments:. *
`no_of_nodes':
The number of vertices
`al':
Pointer to an uninitialized `igraph_adjlist_t' object.
*Returns:. *
`'
Error code.
Time complexity: O(|V|), linear in the number of vertices.
File: igraph_reference_manual.info, Node: igraph_adjlist_init_complementer --- Adjacency lists for the complementer graph, Next: igraph_adjlist_destroy --- Deallocate memory, Prev: igraph_adjlist_init_empty --- Initialize an empty adjacency list, Up: Adjacent vertices
7.10.1.3 igraph_adjlist_init_complementer -- Adjacency lists for the complementer graph
.......................................................................................
int igraph_adjlist_init_complementer(const igraph_t *graph,
igraph_adjlist_t *al,
igraph_neimode_t mode,
igraph_bool_t loops);
This function creates adjacency lists for the complementer of the
input graph. In the complementer graph all edges are present which are
not present in the original graph. Multiple edges in the input graph
are ignored.
*Arguments:. *
`graph':
The input graph.
`al':
Pointer to a not yet initialized adjacency list.
`mode':
Constant specifying whether outgoing (` IGRAPH_OUT' ), incoming (`
IGRAPH_IN' ), or both (` IGRAPH_ALL' ) types of neighbors (in the
complementer graph) to include in the adjacency list. It is
ignored for undirected networks.
`loops':
Whether to consider loop edges.
*Returns:. *
`'
Error code.
Time complexity: O(|V|^2+|E|), quadratic in the number of vertices.
File: igraph_reference_manual.info, Node: igraph_adjlist_destroy --- Deallocate memory, Next: igraph_adjlist_get --- Query a vector in an adjlist, Prev: igraph_adjlist_init_complementer --- Adjacency lists for the complementer graph, Up: Adjacent vertices
7.10.1.4 igraph_adjlist_destroy -- Deallocate memory
....................................................
void igraph_adjlist_destroy(igraph_adjlist_t *al);
Free all memory allocated for an adjacency list.
*Arguments:. *
`al':
The adjacency list to destroy.
Time complexity: depends on memory management.
File: igraph_reference_manual.info, Node: igraph_adjlist_get --- Query a vector in an adjlist, Next: igraph_adjlist_clear --- Removes all edges from an adjacency list_, Prev: igraph_adjlist_destroy --- Deallocate memory, Up: Adjacent vertices
7.10.1.5 igraph_adjlist_get -- Query a vector in an adjlist
...........................................................
#define igraph_adjlist_get(al,no)
Returns a pointer to an `igraph_vector_int_t' object from an
adjacency list. The vector can be modified as desired.
*Arguments:. *
`al':
The adjacency list object.
`no':
The vertex of which the vertex of adjacent vertices are returned.
*Returns:. *
`'
Pointer to the `igraph_vector_int_t' object.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_adjlist_clear --- Removes all edges from an adjacency list_, Next: igraph_adjlist_sort --- Sort each vector in an adjacency list_, Prev: igraph_adjlist_get --- Query a vector in an adjlist, Up: Adjacent vertices
7.10.1.6 igraph_adjlist_clear -- Removes all edges from an adjacency list.
..........................................................................
void igraph_adjlist_clear(igraph_adjlist_t *al);
*Arguments:. *
`al':
The adjacency list. Time complexity: depends on memory
management, typically O(n), where n is the total number of
elements in the adjacency list.
File: igraph_reference_manual.info, Node: igraph_adjlist_sort --- Sort each vector in an adjacency list_, Next: igraph_adjlist_simplify --- Simplify, Prev: igraph_adjlist_clear --- Removes all edges from an adjacency list_, Up: Adjacent vertices
7.10.1.7 igraph_adjlist_sort -- Sort each vector in an adjacency list.
......................................................................
void igraph_adjlist_sort(igraph_adjlist_t *al);
Sorts every vector of the adjacency list.
*Arguments:. *
`al':
The adjacency list.
Time complexity: O(n log n), n is the total number of elements in
the adjacency list.
File: igraph_reference_manual.info, Node: igraph_adjlist_simplify --- Simplify, Prev: igraph_adjlist_sort --- Sort each vector in an adjacency list_, Up: Adjacent vertices
7.10.1.8 igraph_adjlist_simplify -- Simplify
............................................
int igraph_adjlist_simplify(igraph_adjlist_t *al);
Simplify an adjacency list, ie. remove loop and multiple edges.
*Arguments:. *
`al':
The adjacency list.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of edges and
vertices.
File: igraph_reference_manual.info, Node: Incident edges, Next: Lazy adjacency list for vertices, Prev: Adjacent vertices, Up: Adjacency lists
7.10.2 Incident edges
---------------------
* Menu:
* igraph_inclist_init --- Initialize an incidence list of edges::
* igraph_inclist_destroy --- Frees all memory allocated for an incidence list.: igraph_inclist_destroy --- Frees all memory allocated for an incidence list_.
* igraph_inclist_get --- Query a vector in an incidence list::
* igraph_inclist_clear --- Removes all edges from an incidence list.: igraph_inclist_clear --- Removes all edges from an incidence list_.
File: igraph_reference_manual.info, Node: igraph_inclist_init --- Initialize an incidence list of edges, Next: igraph_inclist_destroy --- Frees all memory allocated for an incidence list_, Up: Incident edges
7.10.2.1 igraph_inclist_init -- Initialize an incidence list of edges
.....................................................................
int igraph_inclist_init(const igraph_t *graph,
igraph_inclist_t *il,
igraph_neimode_t mode);
Create a list of vectors containing the incident edges for all
vertices. The incidence list is independent of the graph after
creation, subsequent changes of the graph object do not update the
incidence list, and changes to the incidence list do not update the
graph.
*Arguments:. *
`graph':
The input graph.
`il':
Pointer to an uninitialized incidence list.
`mode':
Constant specifying whether incoming edges (` IGRAPH_IN' ),
outgoing edges (` IGRAPH_OUT' ) or both (` IGRAPH_ALL' ) to
include in the incidence lists of directed graphs. It is ignored
for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
File: igraph_reference_manual.info, Node: igraph_inclist_destroy --- Frees all memory allocated for an incidence list_, Next: igraph_inclist_get --- Query a vector in an incidence list, Prev: igraph_inclist_init --- Initialize an incidence list of edges, Up: Incident edges
7.10.2.2 igraph_inclist_destroy -- Frees all memory allocated for an incidence list.
....................................................................................
void igraph_inclist_destroy(igraph_inclist_t *il);
*Arguments:. *
`eal':
The incidence list to destroy.
Time complexity: depends on memory management.
File: igraph_reference_manual.info, Node: igraph_inclist_get --- Query a vector in an incidence list, Next: igraph_inclist_clear --- Removes all edges from an incidence list_, Prev: igraph_inclist_destroy --- Frees all memory allocated for an incidence list_, Up: Incident edges
7.10.2.3 igraph_inclist_get -- Query a vector in an incidence list
..................................................................
#define igraph_inclist_get(il,no)
Returns a pointer to an `igraph_vector_t' object from an incidence
list containing edge ids. The vector can be modified, resized, etc. as
desired.
*Arguments:. *
`graph':
il The incidence list.
`no':
The vertex for which the incident edges are returned.
*Returns:. *
`'
Pointer to an `igraph_vector_t' object.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_inclist_clear --- Removes all edges from an incidence list_, Prev: igraph_inclist_get --- Query a vector in an incidence list, Up: Incident edges
7.10.2.4 igraph_inclist_clear -- Removes all edges from an incidence list.
..........................................................................
void igraph_inclist_clear(igraph_inclist_t *il);
*Arguments:. *
`il':
The incidence list. Time complexity: depends on memory
management, typically O(n), where n is the total number of
elements in the incidence list.
File: igraph_reference_manual.info, Node: Lazy adjacency list for vertices, Next: Lazy incidence list for edges, Prev: Incident edges, Up: Adjacency lists
7.10.3 Lazy adjacency list for vertices
---------------------------------------
* Menu:
* igraph_lazy_adjlist_init --- Constructor::
* igraph_lazy_adjlist_destroy --- Deallocate memory::
* igraph_lazy_adjlist_get --- Query neighbor vertices::
* igraph_lazy_adjlist_clear --- Removes all edges from a lazy adjacency list.: igraph_lazy_adjlist_clear --- Removes all edges from a lazy adjacency list_.
File: igraph_reference_manual.info, Node: igraph_lazy_adjlist_init --- Constructor, Next: igraph_lazy_adjlist_destroy --- Deallocate memory, Up: Lazy adjacency list for vertices
7.10.3.1 igraph_lazy_adjlist_init -- Constructor
................................................
int igraph_lazy_adjlist_init(const igraph_t *graph,
igraph_lazy_adjlist_t *al,
igraph_neimode_t mode,
igraph_lazy_adlist_simplify_t simplify);
Create a lazy adjacency list for vertices. This function only
allocates some memory for storing the vectors of an adjacency list, but
the neighbor vertices are not queried, only at the
`igraph_lazy_adjlist_get()' (*note igraph_lazy_adjlist_get --- Query
neighbor vertices::) calls.
*Arguments:. *
`graph':
The input graph.
`al':
Pointer to an uninitialized adjacency list object.
`mode':
Constant, it gives whether incoming edges (` IGRAPH_IN' ),
outgoing edges (` IGRPAH_OUT' ) or both types of edges (`
IGRAPH_ALL' ) are considered. It is ignored for undirected graphs.
`simplify':
Constant, it gives whether to simplify the vectors in the
adjacency list (` IGRAPH_SIMPLIFY' ) or not (`
IGRAPH_DONT_SIMPLIFY' ).
*Returns:. *
`'
Error code.
Time complexity: O(|V|), the number of vertices, possibly, but
depends on the underlying memory management too.
File: igraph_reference_manual.info, Node: igraph_lazy_adjlist_destroy --- Deallocate memory, Next: igraph_lazy_adjlist_get --- Query neighbor vertices, Prev: igraph_lazy_adjlist_init --- Constructor, Up: Lazy adjacency list for vertices
7.10.3.2 igraph_lazy_adjlist_destroy -- Deallocate memory
.........................................................
void igraph_lazy_adjlist_destroy(igraph_lazy_adjlist_t *al);
Free all allocated memory for a lazy adjacency list.
*Arguments:. *
`al':
The adjacency list to deallocate.
Time complexity: depends on the memory management.
File: igraph_reference_manual.info, Node: igraph_lazy_adjlist_get --- Query neighbor vertices, Next: igraph_lazy_adjlist_clear --- Removes all edges from a lazy adjacency list_, Prev: igraph_lazy_adjlist_destroy --- Deallocate memory, Up: Lazy adjacency list for vertices
7.10.3.3 igraph_lazy_adjlist_get -- Query neighbor vertices
...........................................................
#define igraph_lazy_adjlist_get(al,no)
If the function is called for the first time for a vertex then the
result is stored in the adjacency list and no further query operations
are needed when the neighbors of the same vertex are queried again.
*Arguments:. *
`al':
The lazy adjacency list.
`no':
The vertex id to query.
*Returns:. *
`'
Pointer to a vector. It is allowed to modify it and modification
does not affect the original graph.
Time complexity: O(d), the number of neighbor vertices for the first
time, O(1) for subsequent calls.
File: igraph_reference_manual.info, Node: igraph_lazy_adjlist_clear --- Removes all edges from a lazy adjacency list_, Prev: igraph_lazy_adjlist_get --- Query neighbor vertices, Up: Lazy adjacency list for vertices
7.10.3.4 igraph_lazy_adjlist_clear -- Removes all edges from a lazy adjacency list.
...................................................................................
void igraph_lazy_adjlist_clear(igraph_lazy_adjlist_t *al);
*Arguments:. *
`al':
The lazy adjacency list. Time complexity: depends on memory
management, typically O(n), where n is the total number of
elements in the adjacency list.
File: igraph_reference_manual.info, Node: Lazy incidence list for edges, Next: Deprecated functions <1>, Prev: Lazy adjacency list for vertices, Up: Adjacency lists
7.10.4 Lazy incidence list for edges
------------------------------------
* Menu:
* igraph_lazy_inclist_init --- Initializes a lazy incidence list of edges::
* igraph_lazy_inclist_destroy --- Deallocates memory::
* igraph_lazy_inclist_get --- Query incident edges::
* igraph_lazy_inclist_clear --- Removes all edges from a lazy incidence list.: igraph_lazy_inclist_clear --- Removes all edges from a lazy incidence list_.
File: igraph_reference_manual.info, Node: igraph_lazy_inclist_init --- Initializes a lazy incidence list of edges, Next: igraph_lazy_inclist_destroy --- Deallocates memory, Up: Lazy incidence list for edges
7.10.4.1 igraph_lazy_inclist_init -- Initializes a lazy incidence list of edges
...............................................................................
int igraph_lazy_inclist_init(const igraph_t *graph,
igraph_lazy_inclist_t *al,
igraph_neimode_t mode);
Create a lazy incidence list for edges. This function only allocates
some memory for storing the vectors of an incidence list, but the
incident edges are not queried, only when `igraph_lazy_inclist_get()'
(*note igraph_lazy_inclist_get --- Query incident edges::) is called.
*Arguments:. *
`graph':
The input graph.
`al':
Pointer to an uninitialized incidence list.
`mode':
Constant, it gives whether incoming edges (` IGRAPH_IN' ),
outgoing edges (` IGRPAH_OUT' ) or both types of edges (`
IGRAPH_ALL' ) are considered. It is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|V|), the number of vertices, possibly. But it
also depends on the underlying memory management.
File: igraph_reference_manual.info, Node: igraph_lazy_inclist_destroy --- Deallocates memory, Next: igraph_lazy_inclist_get --- Query incident edges, Prev: igraph_lazy_inclist_init --- Initializes a lazy incidence list of edges, Up: Lazy incidence list for edges
7.10.4.2 igraph_lazy_inclist_destroy -- Deallocates memory
..........................................................
void igraph_lazy_inclist_destroy(igraph_lazy_inclist_t *il);
Frees all allocated memory for a lazy incidence list.
*Arguments:. *
`al':
The incidence list to deallocate.
Time complexity: depends on memory management.
File: igraph_reference_manual.info, Node: igraph_lazy_inclist_get --- Query incident edges, Next: igraph_lazy_inclist_clear --- Removes all edges from a lazy incidence list_, Prev: igraph_lazy_inclist_destroy --- Deallocates memory, Up: Lazy incidence list for edges
7.10.4.3 igraph_lazy_inclist_get -- Query incident edges
........................................................
#define igraph_lazy_inclist_get(al,no)
If the function is called for the first time for a vertex, then the
result is stored in the incidence list and no further query operations
are needed when the incident edges of the same vertex are queried again.
*Arguments:. *
`al':
The lazy incidence list object.
`no':
The vertex id to query.
*Returns:. *
`'
Pointer to a vector. It is allowed to modify it and modification
does not affect the original graph.
Time complexity: O(d), the number of incident edges for the first
time, O(1) for subsequent calls with the same `no' argument.
File: igraph_reference_manual.info, Node: igraph_lazy_inclist_clear --- Removes all edges from a lazy incidence list_, Prev: igraph_lazy_inclist_get --- Query incident edges, Up: Lazy incidence list for edges
7.10.4.4 igraph_lazy_inclist_clear -- Removes all edges from a lazy incidence list.
...................................................................................
void igraph_lazy_inclist_clear(igraph_lazy_inclist_t *il);
*Arguments:. *
`il':
The lazy incidence list. Time complexity: depends on memory
management, typically O(n), where n is the total number of
elements in the incidence list.
File: igraph_reference_manual.info, Node: Deprecated functions <1>, Prev: Lazy incidence list for edges, Up: Adjacency lists
7.10.5 Deprecated functions
---------------------------
* Menu:
* igraph_adjedgelist_init --- Initialize an incidence list of edges::
* igraph_adjedgelist_destroy --- Frees all memory allocated for an incidence list.: igraph_adjedgelist_destroy --- Frees all memory allocated for an incidence list_.
* igraph_adjedgelist_get --- Query a vector in an incidence list::
* igraph_lazy_adjedgelist_init --- Initializes a lazy incidence list of edges::
* igraph_lazy_adjedgelist_destroy --- Frees all memory allocated for an incidence list.: igraph_lazy_adjedgelist_destroy --- Frees all memory allocated for an incidence list_.
* igraph_lazy_adjedgelist_get --- Query a vector in a lazy incidence list::
File: igraph_reference_manual.info, Node: igraph_adjedgelist_init --- Initialize an incidence list of edges, Next: igraph_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Up: Deprecated functions <1>
7.10.5.1 igraph_adjedgelist_init -- Initialize an incidence list of edges
.........................................................................
int igraph_adjedgelist_init(const igraph_t *graph,
igraph_inclist_t *il,
igraph_neimode_t mode);
This function was superseded by `igraph_inclist_init()' (*note
igraph_inclist_init --- Initialize an incidence list of edges::) in
igraph 0.6. Please use `igraph_inclist_init()' (*note
igraph_inclist_init --- Initialize an incidence list of edges::)
instead of this function.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: igraph_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Next: igraph_adjedgelist_get --- Query a vector in an incidence list, Prev: igraph_adjedgelist_init --- Initialize an incidence list of edges, Up: Deprecated functions <1>
7.10.5.2 igraph_adjedgelist_destroy -- Frees all memory allocated for an incidence list.
........................................................................................
void igraph_adjedgelist_destroy(igraph_inclist_t *il);
This function was superseded by `igraph_inclist_destroy()' (*note
igraph_inclist_destroy --- Frees all memory allocated for an incidence
list_::) in igraph 0.6. Please use `igraph_inclist_destroy()' (*note
igraph_inclist_destroy --- Frees all memory allocated for an incidence
list_::) instead of this function.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: igraph_adjedgelist_get --- Query a vector in an incidence list, Next: igraph_lazy_adjedgelist_init --- Initializes a lazy incidence list of edges, Prev: igraph_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Up: Deprecated functions <1>
7.10.5.3 igraph_adjedgelist_get -- Query a vector in an incidence list
......................................................................
#define igraph_adjedgelist_get(ael,no)
This macro was superseded by `igraph_inclist_get()' (*note
igraph_inclist_get --- Query a vector in an incidence list::) in igraph
0.6. Please use `igraph_inclist_get()' (*note igraph_inclist_get ---
Query a vector in an incidence list::) instead of this macro.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: igraph_lazy_adjedgelist_init --- Initializes a lazy incidence list of edges, Next: igraph_lazy_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Prev: igraph_adjedgelist_get --- Query a vector in an incidence list, Up: Deprecated functions <1>
7.10.5.4 igraph_lazy_adjedgelist_init -- Initializes a lazy incidence list of edges
...................................................................................
int igraph_lazy_adjedgelist_init(const igraph_t *graph,
igraph_lazy_inclist_t *il,
igraph_neimode_t mode);
This function was superseded by `igraph_lazy_inclist_init()' (*note
igraph_lazy_inclist_init --- Initializes a lazy incidence list of
edges::) in igraph 0.6. Please use `igraph_lazy_inclist_init()' (*note
igraph_lazy_inclist_init --- Initializes a lazy incidence list of
edges::) instead of this function.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: igraph_lazy_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Next: igraph_lazy_adjedgelist_get --- Query a vector in a lazy incidence list, Prev: igraph_lazy_adjedgelist_init --- Initializes a lazy incidence list of edges, Up: Deprecated functions <1>
7.10.5.5 igraph_lazy_adjedgelist_destroy -- Frees all memory allocated for an incidence list.
.............................................................................................
void igraph_lazy_adjedgelist_destroy(igraph_lazy_inclist_t *il);
This function was superseded by `igraph_lazy_inclist_destroy()'
(*note igraph_lazy_inclist_destroy --- Deallocates memory::) in igraph
0.6. Please use `igraph_lazy_inclist_destroy()' (*note
igraph_lazy_inclist_destroy --- Deallocates memory::) instead of this
function.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: igraph_lazy_adjedgelist_get --- Query a vector in a lazy incidence list, Prev: igraph_lazy_adjedgelist_destroy --- Frees all memory allocated for an incidence list_, Up: Deprecated functions <1>
7.10.5.6 igraph_lazy_adjedgelist_get -- Query a vector in a lazy incidence list
...............................................................................
#define igraph_lazy_adjedgelist_get(al,no)
This macro was superseded by `igraph_lazy_inclist_get()' (*note
igraph_lazy_inclist_get --- Query incident edges::) in igraph 0.6.
Please use `igraph_lazy_inclist_get()' (*note igraph_lazy_inclist_get
--- Query incident edges::) instead of this macro.
Deprecated in version 0.6.
File: igraph_reference_manual.info, Node: Random numbers, Next: Graph Generators, Prev: Data structure library; vector; matrix; other data types, Up: Top
8 Random numbers
****************
* Menu:
* About random numbers in igraph, use cases: About random numbers in igraph; use cases.
* The default random number generator::
* Creating random number generators::
* Generating random numbers::
* Supported random number generators::
* Use cases::
File: igraph_reference_manual.info, Node: About random numbers in igraph; use cases, Next: The default random number generator, Up: Random numbers
8.1 About random numbers in igraph, use cases
=============================================
Some algorithms in igraph, e.g. the generation of random graphs,
require random number generators (RNGs). Prior to version 0.6 igraph
did not have a sophisticated way to deal with random number generators
at the C level, but this has changed. From version 0.6 different and
multiple random number generators are supported.
File: igraph_reference_manual.info, Node: The default random number generator, Next: Creating random number generators, Prev: About random numbers in igraph; use cases, Up: Random numbers
8.2 The default random number generator
=======================================
* Menu:
* igraph_rng_default --- Query the default random number generator.: igraph_rng_default --- Query the default random number generator_.
* igraph_rng_set_default --- Set the default igraph random number generator::
File: igraph_reference_manual.info, Node: igraph_rng_default --- Query the default random number generator_, Next: igraph_rng_set_default --- Set the default igraph random number generator, Up: The default random number generator
8.2.1 igraph_rng_default -- Query the default random number generator.
----------------------------------------------------------------------
igraph_rng_t *igraph_rng_default();
*Returns:. *
`'
A pointer to the default random number generator.
*See also:. *
`'
igraph_rng_set_default()
File: igraph_reference_manual.info, Node: igraph_rng_set_default --- Set the default igraph random number generator, Prev: igraph_rng_default --- Query the default random number generator_, Up: The default random number generator
8.2.2 igraph_rng_set_default -- Set the default igraph random number generator
------------------------------------------------------------------------------
void igraph_rng_set_default(igraph_rng_t *rng);
*Arguments:. *
`rng':
The random number generator to use as default from now on. Calling
`igraph_rng_destroy()' (*note igraph_rng_destroy --- Deallocate
memory associated with a random number generator::) on it, while
it is still being used as the default will result craches and/or
unpredictable results.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Creating random number generators, Next: Generating random numbers, Prev: The default random number generator, Up: Random numbers
8.3 Creating random number generators
=====================================
* Menu:
* igraph_rng_init --- Initialize a random number generator::
* igraph_rng_destroy --- Deallocate memory associated with a random number generator::
* igraph_rng_seed --- Set the seed of a random number generator::
* igraph_rng_min --- Query the minimum possible integer for a random number generator::
* igraph_rng_max --- Query the maximum possible integer for a random number generator::
* igraph_rng_name --- Query the type of a random number generator::
File: igraph_reference_manual.info, Node: igraph_rng_init --- Initialize a random number generator, Next: igraph_rng_destroy --- Deallocate memory associated with a random number generator, Up: Creating random number generators
8.3.1 igraph_rng_init -- Initialize a random number generator
-------------------------------------------------------------
int igraph_rng_init(igraph_rng_t *rng, const igraph_rng_type_t *type);
This function allocates memory for a random number generator, with
the given type, and sets its seed to the default.
*Arguments:. *
`rng':
Pointer to an uninitialized RNG.
`type':
The type of the RNG, please see the documentation for the
supported types.
*Returns:. *
`'
Error code.
Time complexity: depends on the type of the generator, but usually
it should be O(1).
File: igraph_reference_manual.info, Node: igraph_rng_destroy --- Deallocate memory associated with a random number generator, Next: igraph_rng_seed --- Set the seed of a random number generator, Prev: igraph_rng_init --- Initialize a random number generator, Up: Creating random number generators
8.3.2 igraph_rng_destroy -- Deallocate memory associated with a random number generator
---------------------------------------------------------------------------------------
void igraph_rng_destroy(igraph_rng_t *rng);
*Arguments:. *
`rng':
The RNG to destroy. Do not destroy an RNG that is used as the
default igraph RNG.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_rng_seed --- Set the seed of a random number generator, Next: igraph_rng_min --- Query the minimum possible integer for a random number generator, Prev: igraph_rng_destroy --- Deallocate memory associated with a random number generator, Up: Creating random number generators
8.3.3 igraph_rng_seed -- Set the seed of a random number generator
------------------------------------------------------------------
int igraph_rng_seed(igraph_rng_t *rng, unsigned long int seed);
*Arguments:. *
`rng':
The RNG.
`seed':
The new seed.
*Returns:. *
`'
Error code.
Time complexity: usually O(1), but may depend on the type of the RNG.
File: igraph_reference_manual.info, Node: igraph_rng_min --- Query the minimum possible integer for a random number generator, Next: igraph_rng_max --- Query the maximum possible integer for a random number generator, Prev: igraph_rng_seed --- Set the seed of a random number generator, Up: Creating random number generators
8.3.4 igraph_rng_min -- Query the minimum possible integer for a random number generator
----------------------------------------------------------------------------------------
unsigned long int igraph_rng_min(igraph_rng_t *rng);
*Arguments:. *
`rng':
The RNG.
*Returns:. *
`'
The smallest possible integer that can be generated by calling
`igraph_rng_get_integer()' (*note igraph_rng_get_integer ---
Generate an integer random number from an interval::) on the RNG.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_rng_max --- Query the maximum possible integer for a random number generator, Next: igraph_rng_name --- Query the type of a random number generator, Prev: igraph_rng_min --- Query the minimum possible integer for a random number generator, Up: Creating random number generators
8.3.5 igraph_rng_max -- Query the maximum possible integer for a random number generator
----------------------------------------------------------------------------------------
unsigned long int igraph_rng_max(igraph_rng_t *rng);
*Arguments:. *
`rng':
The RNG.
*Returns:. *
`'
The largest possible integer that can be generated by calling
`igraph_rng_get_integer()' (*note igraph_rng_get_integer ---
Generate an integer random number from an interval::) on the RNG.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_rng_name --- Query the type of a random number generator, Prev: igraph_rng_max --- Query the maximum possible integer for a random number generator, Up: Creating random number generators
8.3.6 igraph_rng_name -- Query the type of a random number generator
--------------------------------------------------------------------
const char *igraph_rng_name(igraph_rng_t *rng);
*Arguments:. *
`rng':
The RNG.
*Returns:. *
`'
The name of the type of the generator. Do not deallocate or change
the returned string pointer.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Generating random numbers, Next: Supported random number generators, Prev: Creating random number generators, Up: Random numbers
8.4 Generating random numbers
=============================
* Menu:
* igraph_rng_get_integer --- Generate an integer random number from an interval::
* igraph_rng_get_unif --- Generate real, uniform random numbers from an interval: igraph_rng_get_unif --- Generate real; uniform random numbers from an interval.
* igraph_rng_get_unif01 --- Generate real, uniform random number from the unit interval: igraph_rng_get_unif01 --- Generate real; uniform random number from the unit interval.
* igraph_rng_get_normal --- Normally distributed random numbers::
* igraph_rng_get_geom --- Generate geometrically distributed random numbers::
* igraph_rng_get_binom --- Generate binomially distributed random numbers::
File: igraph_reference_manual.info, Node: igraph_rng_get_integer --- Generate an integer random number from an interval, Next: igraph_rng_get_unif --- Generate real; uniform random numbers from an interval, Up: Generating random numbers
8.4.1 igraph_rng_get_integer -- Generate an integer random number from an interval
----------------------------------------------------------------------------------
long int igraph_rng_get_integer(igraph_rng_t *rng,
long int l, long int h);
*Arguments:. *
`rng':
Pointer to the RNG to use for the generation. Use
`igraph_rng_default()' (*note igraph_rng_default --- Query the
default random number generator_::) here to use the default igraph
RNG.
`l':
Lower limit, inclusive, it can be negative as well.
`h':
Upper limit, inclusive, it can be negative as well, but it should
be at least ` l' .
*Returns:. *
`'
The generated random integer.
Time complexity: depends on the generator, but should be usually
O(1).
File: igraph_reference_manual.info, Node: igraph_rng_get_unif --- Generate real; uniform random numbers from an interval, Next: igraph_rng_get_unif01 --- Generate real; uniform random number from the unit interval, Prev: igraph_rng_get_integer --- Generate an integer random number from an interval, Up: Generating random numbers
8.4.2 igraph_rng_get_unif -- Generate real, uniform random numbers from an interval
-----------------------------------------------------------------------------------
igraph_real_t igraph_rng_get_unif(igraph_rng_t *rng,
igraph_real_t l, igraph_real_t h);
*Arguments:. *
`rng':
Pointer to the RNG to use. Use `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number
generator_::) here to use the default igraph RNG.
`l':
The lower bound, it can be negative.
`h':
The upper bound, it can be negative, but it has to be larger than
the lower bound.
*Returns:. *
`'
The generated uniformly distributed random number.
Time complexity: depends on the type of the RNG.
File: igraph_reference_manual.info, Node: igraph_rng_get_unif01 --- Generate real; uniform random number from the unit interval, Next: igraph_rng_get_normal --- Normally distributed random numbers, Prev: igraph_rng_get_unif --- Generate real; uniform random numbers from an interval, Up: Generating random numbers
8.4.3 igraph_rng_get_unif01 -- Generate real, uniform random number from the unit interval
------------------------------------------------------------------------------------------
igraph_real_t igraph_rng_get_unif01(igraph_rng_t *rng);
*Arguments:. *
`rng':
Pointer to the RNG to use. Use `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number
generator_::) here to use the default igraph RNG.
*Returns:. *
`'
The generated uniformly distributed random number.
Time complexity: depends on the type of the RNG.
File: igraph_reference_manual.info, Node: igraph_rng_get_normal --- Normally distributed random numbers, Next: igraph_rng_get_geom --- Generate geometrically distributed random numbers, Prev: igraph_rng_get_unif01 --- Generate real; uniform random number from the unit interval, Up: Generating random numbers
8.4.4 igraph_rng_get_normal -- Normally distributed random numbers
------------------------------------------------------------------
igraph_real_t igraph_rng_get_normal(igraph_rng_t *rng,
igraph_real_t m, igraph_real_t s);
*Arguments:. *
`rng':
Pointer to the RNG to use. Use `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number
generator_::) here to use the default igraph RNG.
`m':
The mean.
`s':
Standard deviation.
*Returns:. *
`'
The generated normally distributed random number.
Time complexity: depends on the type of the RNG.
File: igraph_reference_manual.info, Node: igraph_rng_get_geom --- Generate geometrically distributed random numbers, Next: igraph_rng_get_binom --- Generate binomially distributed random numbers, Prev: igraph_rng_get_normal --- Normally distributed random numbers, Up: Generating random numbers
8.4.5 igraph_rng_get_geom -- Generate geometrically distributed random numbers
------------------------------------------------------------------------------
igraph_real_t igraph_rng_get_geom(igraph_rng_t *rng, igraph_real_t p);
*Arguments:. *
`rng':
Pointer to the RNG to use. Use `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number
generator_::) here to use the default igraph RNG.
`p':
The probability of success in each trial. Must be larger than zero
and smaller or equal to 1.
*Returns:. *
`'
The generated geometrically distributed random number.
Time complexity: depends on the type of the RNG.
File: igraph_reference_manual.info, Node: igraph_rng_get_binom --- Generate binomially distributed random numbers, Prev: igraph_rng_get_geom --- Generate geometrically distributed random numbers, Up: Generating random numbers
8.4.6 igraph_rng_get_binom -- Generate binomially distributed random numbers
----------------------------------------------------------------------------
igraph_real_t igraph_rng_get_binom(igraph_rng_t *rng, long int n,
igraph_real_t p);
*Arguments:. *
`rng':
Pointer to the RNG to use. Use `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number
generator_::) here to use the default igraph RNG.
`n':
Number of observations.
`p':
Probability of an event.
*Returns:. *
`'
The generated binomially distributed random number.
Time complexity: depends on the type of the RNG.
File: igraph_reference_manual.info, Node: Supported random number generators, Next: Use cases, Prev: Generating random numbers, Up: Random numbers
8.5 Supported random number generators
======================================
By default igraph uses the MT19937 generator. Prior to igraph version
0.6, the generator supplied by the standard C library was used. This
means the GLIBC2 generator on GNU libc 2 systems, and maybe the RAND
generator on others.
* Menu:
* igraph_rngtype_mt19937 --- The MT19937 random number generator::
* igraph_rngtype_glibc2 --- The random number generator type introduced in GNU libc 2::
* igraph_rngtype_rand --- The old BSD rand/stand random number generator::
File: igraph_reference_manual.info, Node: igraph_rngtype_mt19937 --- The MT19937 random number generator, Next: igraph_rngtype_glibc2 --- The random number generator type introduced in GNU libc 2, Up: Supported random number generators
8.5.1 igraph_rngtype_mt19937 -- The MT19937 random number generator
-------------------------------------------------------------------
const igraph_rng_type_t igraph_rngtype_mt19937 = {
/* name= */ "MT19937",
/* min= */ 0,
/* max= */ 0xffffffffUL,
/* init= */ igraph_rng_mt19937_init,
/* destroy= */ igraph_rng_mt19937_destroy,
/* seed= */ igraph_rng_mt19937_seed,
/* get= */ igraph_rng_mt19937_get,
/* get_real= */ igraph_rng_mt19937_get_real,
/* get_norm= */ 0,
/* get_geom= */ 0,
/* get_binom= */ 0,
/* get_exp= */ 0
};
The MT19937 generator of Makoto Matsumoto and Takuji Nishimura is a
variant of the twisted generalized feedback shift-register algorithm,
and is known as the "Mersenne Twister" generator. It has a Mersenne
prime period of 2^19937 - 1 (about 10^6000) and is equi-distributed in
623 dimensions. It has passed the diehard statistical tests. It uses
624 words of state per generator and is comparable in speed to the
other generators. The original generator used a default seed of 4357
and choosing s equal to zero in gsl_rng_set reproduces this. Later
versions switched to 5489 as the default seed, you can choose this
explicitly via igraph_rng_seed instead if you require it. For more
information see, Makoto Matsumoto and Takuji Nishimura, "Mersenne
Twister: A 623-dimensionally equidistributed uniform pseudorandom number
generator". ACM Transactions on Modeling and Computer Simulation, Vol.
8, No. 1 (Jan. 1998), Pages 3-30 The generator igraph_rngtype_mt19937
uses the second revision of the seeding procedure published by the two
authors above in 2002. The original seeding procedures could cause
spurious artifacts for some seed values. This generator was ported
from the GNU Scientific Library.
File: igraph_reference_manual.info, Node: igraph_rngtype_glibc2 --- The random number generator type introduced in GNU libc 2, Next: igraph_rngtype_rand --- The old BSD rand/stand random number generator, Prev: igraph_rngtype_mt19937 --- The MT19937 random number generator, Up: Supported random number generators
8.5.2 igraph_rngtype_glibc2 -- The random number generator type introduced in GNU libc 2
----------------------------------------------------------------------------------------
const igraph_rng_type_t igraph_rngtype_glibc2 = {
/* name= */ "LIBC",
/* min= */ 0,
/* max= */ RAND_MAX,
/* init= */ igraph_rng_glibc2_init,
/* destroy= */ igraph_rng_glibc2_destroy,
/* seed= */ igraph_rng_glibc2_seed,
/* get= */ igraph_rng_glibc2_get,
/* get_real= */ igraph_rng_glibc2_get_real,
/* get_norm= */ 0,
/* get_geom= */ 0,
/* get_binom= */ 0,
/* get_exp= */ 0
};
It is a linear feedback shift register generator with a 128-byte
buffer. This generator was the default prior to igraph version 0.6, at
least on systems relying on GNU libc. This generator was ported from
the GNU Scientific Library.
File: igraph_reference_manual.info, Node: igraph_rngtype_rand --- The old BSD rand/stand random number generator, Prev: igraph_rngtype_glibc2 --- The random number generator type introduced in GNU libc 2, Up: Supported random number generators
8.5.3 igraph_rngtype_rand -- The old BSD rand/stand random number generator
---------------------------------------------------------------------------
const igraph_rng_type_t igraph_rngtype_rand = {
/* name= */ "RAND",
/* min= */ 0,
/* max= */ 0x7fffffffUL,
/* init= */ igraph_rng_rand_init,
/* destroy= */ igraph_rng_rand_destroy,
/* seed= */ igraph_rng_rand_seed,
/* get= */ igraph_rng_rand_get,
/* get_real= */ igraph_rng_rand_get_real,
/* get_norm= */ 0,
/* get_geom= */ 0,
/* get_binom= */ 0,
/* get_exp= */ 0
};
The sequence is x_{n+1} = (a x_n + c) mod m with a = 1103515245, c =
12345 and m = 2^31 = 2147483648. The seed specifies the initial value,
x_1. The theoretical value of x_{10001} is 1910041713. The period of
this generator is 2^31. This generator is not very good - the low bits
of successive numbers are correlated. This generator was ported from
the GNU Scientific Library.
File: igraph_reference_manual.info, Node: Use cases, Prev: Supported random number generators, Up: Random numbers
8.6 Use cases
=============
* Menu:
* Normal (default) use: Normal [default] use.
* Reproducible simulations::
* Changing the default generator::
* Using multiple generators::
* Example::
File: igraph_reference_manual.info, Node: Normal [default] use, Next: Reproducible simulations, Up: Use cases
8.6.1 Normal (default) use
--------------------------
If the user does not use any of the RNG functions explicitly, but calls
some of the randomized igraph functions, then a default RNG is set up
the first time an igraph function needs random numbers. The seed of
this RNG is the output of the ` time(0)' function call, using the `
time' function from the standard C library. This ensures that igraph
creates a different random graph, each time the C program is called.
The created default generator is stored internally and can be
queried with the `igraph_rng_default()' (*note igraph_rng_default ---
Query the default random number generator_::) function.
File: igraph_reference_manual.info, Node: Reproducible simulations, Next: Changing the default generator, Prev: Normal [default] use, Up: Use cases
8.6.2 Reproducible simulations
------------------------------
If reproducible results are needed, then the user should set the seed
of the default random number generator explicitly, using the
`igraph_rng_seed()' (*note igraph_rng_seed --- Set the seed of a random
number generator::) function on the default generator,
`igraph_rng_default()' (*note igraph_rng_default --- Query the default
random number generator_::). When setting the seed to the same number,
igraph generates exactly the same random graph (or series of random
graphs).
File: igraph_reference_manual.info, Node: Changing the default generator, Next: Using multiple generators, Prev: Reproducible simulations, Up: Use cases
8.6.3 Changing the default generator
------------------------------------
By default igraph uses the `igraph_rng_default()' (*note
igraph_rng_default --- Query the default random number generator_::)
random number generator. This can be changed any time by calling
`igraph_rng_set_default()' (*note igraph_rng_set_default --- Set the
default igraph random number generator::), with an already initialized
random number generator. Note that the old (replaced) generator is not
destroyed, so no memory is deallocated.
File: igraph_reference_manual.info, Node: Using multiple generators, Next: Example, Prev: Changing the default generator, Up: Use cases
8.6.4 Using multiple generators
-------------------------------
igraph also provides functions to set up multiple random number
generators, using the `igraph_rng_init()' (*note igraph_rng_init ---
Initialize a random number generator::) function, and then generating
random numbers from them, e.g. with `igraph_rng_get_integer()' (*note
igraph_rng_get_integer --- Generate an integer random number from an
interval::) and/or `igraph_rng_get_unif()' (*note igraph_rng_get_unif
--- Generate real; uniform random numbers from an interval::) calls.
Note that initializing a new random number generator is independent
of the generator that the igraph functions themselves use. If you want
to replace that, then please use `igraph_rng_set_default()' (*note
igraph_rng_set_default --- Set the default igraph random number
generator::).
File: igraph_reference_manual.info, Node: Example, Prev: Using multiple generators, Up: Use cases
8.6.5 Example
-------------
* File examples/simple/random_seed.c*
File: igraph_reference_manual.info, Node: Graph Generators, Next: Games on Graphs, Prev: Random numbers, Up: Top
9 Graph Generators
******************
Graph generators create graphs.
Almost all functions which create graph objects are documented here.
The exceptions are `igraph_subgraph()' (*note igraph_subgraph ---
Creates a subgraph induced by the specified vertices_::) and alike,
these create graphs based on another graph.
* Menu:
* Deterministic Graph Generators::
* Games; Randomized Graph Generators::
File: igraph_reference_manual.info, Node: Deterministic Graph Generators, Next: Games; Randomized Graph Generators, Up: Graph Generators
9.1 Deterministic Graph Generators
==================================
* Menu:
* igraph_create --- Creates a graph with the specified edges.: igraph_create --- Creates a graph with the specified edges_.
* igraph_small --- Shorthand to create a short graph, giving the edges as arguments.: igraph_small --- Shorthand to create a short graph; giving the edges as arguments_.
* igraph_adjacency --- Creates a graph object from an adjacency matrix.: igraph_adjacency --- Creates a graph object from an adjacency matrix_.
* igraph_weighted_adjacency --- Creates a graph object from a weighted adjacency matrix.: igraph_weighted_adjacency --- Creates a graph object from a weighted adjacency matrix_.
* igraph_adjlist --- Create a graph from an adjacency list::
* igraph_star --- Creates a star graph, every vertex connects only to the center.: igraph_star --- Creates a star graph; every vertex connects only to the center_.
* igraph_lattice --- Creates most kinds of lattices.: igraph_lattice --- Creates most kinds of lattices_.
* igraph_ring --- Creates a ring graph, a one dimensional lattice.: igraph_ring --- Creates a ring graph; a one dimensional lattice_.
* igraph_tree --- Creates a tree in which almost all vertices have the same number of children.: igraph_tree --- Creates a tree in which almost all vertices have the same number of children_.
* igraph_full --- Creates a full graph (directed or undirected, with or without loops). : igraph_full --- Creates a full graph [directed or undirected; with or without loops]_.
* igraph_full_citation --- Creates a full citation graph::
* igraph_famous --- Create a famous graph by simply providing its name::
* igraph_lcf --- Create a graph from LCF notation::
* igraph_lcf_vector --- Create a graph from LCF notation::
* igraph_atlas --- Create a small graph from the Graph Atlas.: igraph_atlas --- Create a small graph from the Graph Atlas_.
* igraph_de_bruijn --- Generate a de Bruijn graph.: igraph_de_bruijn --- Generate a de Bruijn graph_.
* igraph_kautz --- Generate a Kautz graph.: igraph_kautz --- Generate a Kautz graph_.
* igraph_extended_chordal_ring --- Create an extended chordal ring::
* igraph_connect_neighborhood --- Connects every vertex to its neighborhood::
File: igraph_reference_manual.info, Node: igraph_create --- Creates a graph with the specified edges_, Next: igraph_small --- Shorthand to create a short graph; giving the edges as arguments_, Up: Deterministic Graph Generators
9.1.1 igraph_create -- Creates a graph with the specified edges.
----------------------------------------------------------------
int igraph_create(igraph_t *graph, const igraph_vector_t *edges,
igraph_integer_t n, igraph_bool_t directed);
*Arguments:. *
`graph':
An uninitialized graph object.
`edges':
The edges to add, the first two elements are the first edge, etc.
`n':
The number of vertices in the graph, if smaller or equal to the
highest vertex id in the `edges' vector it will be increased
automatically. So it is safe to give 0 here.
`directed':
Boolean, whether to create a directed graph or not. If yes, then
the first edge points from the first vertex id in `edges' to the
second, etc.
*Returns:. *
`'
Error code: `IGRAPH_EINVEVECTOR': invalid edges vector (odd number
of vertices). `IGRAPH_EINVVID': invalid (negative) vertex id.
Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| the
number of edges in the graph.
* File examples/simple/igraph_create.c*
File: igraph_reference_manual.info, Node: igraph_small --- Shorthand to create a short graph; giving the edges as arguments_, Next: igraph_adjacency --- Creates a graph object from an adjacency matrix_, Prev: igraph_create --- Creates a graph with the specified edges_, Up: Deterministic Graph Generators
9.1.2 igraph_small -- Shorthand to create a short graph, giving the edges as arguments.
---------------------------------------------------------------------------------------
int igraph_small(igraph_t *graph, igraph_integer_t n, igraph_bool_t directed,
...);
This function is handy when a relatively small graph needs to be
created. Instead of giving the edges as a vector, they are given
simply as arguments and a '-1' needs to be given after the last
meaningful edge argument.
Note that only graphs which have vertices less than the highest
value of the 'int' type can be created this way. If you give larger
values then the result is undefined.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object. The result will be
stored here.
`n':
The number of vertices in the graph; a nonnegative integer.
`directed':
Logical constant; gives whether the graph should be directed.
Supported values are:
`IGRAPH_DIRECTED'
The graph to be created will be _directed._
`IGRAPH_UNDIRECTED'
The graph to be created will be _undirected._
`...':
The additional arguments giving the edges of the graph. Don't
forget to supply an additional '-1' after the last (meaningful)
argument.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph to create.
* File examples/simple/igraph_small.c*
File: igraph_reference_manual.info, Node: igraph_adjacency --- Creates a graph object from an adjacency matrix_, Next: igraph_weighted_adjacency --- Creates a graph object from a weighted adjacency matrix_, Prev: igraph_small --- Shorthand to create a short graph; giving the edges as arguments_, Up: Deterministic Graph Generators
9.1.3 igraph_adjacency -- Creates a graph object from an adjacency matrix.
--------------------------------------------------------------------------
int igraph_adjacency(igraph_t *graph, igraph_matrix_t *adjmatrix,
igraph_adjacency_t mode);
The order of the vertices in the matrix is preserved, i.e. the vertex
corresponding to the first row/column will be vertex with id 0, the
next row is for vertex 1, etc.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`adjmatrix':
The adjacency matrix. How it is interpreted depends on the `mode'
argument.
`mode':
Constant to specify how the given matrix is interpreted as an
adjacency matrix. Possible values (A(i,j) is the element in row i
and column j in the adjacency matrix `adjmatrix'):
`IGRAPH_ADJ_DIRECTED'
the graph will be directed and an element gives the number of
edges between two vertices.
`IGRAPH_ADJ_UNDIRECTED'
this is the same as `IGRAPH_ADJ_MAX', for convenience.
`IGRAPH_ADJ_MAX'
undirected graph will be created and the number of edges
between vertices i and j is max(A(i,j), A(j,i)).
`IGRAPH_ADJ_MIN'
undirected graph will be created with min(A(i,j), A(j,i))
edges between vertices i and j.
`IGRAPH_ADJ_PLUS '
undirected graph will be created with A(i,j)+A(j,i) edges
between vertices i and j.
`IGRAPH_ADJ_UPPER '
undirected graph will be created, only the upper right
triangle (including the diagonal) is used for the number of
edges.
`IGRAPH_ADJ_LOWER '
undirected graph will be created, only the lower left
triangle (including the diagonal) is used for creating the
edges.
*Returns:. *
`'
Error code, `IGRAPH_NONSQUARE': non-square matrix.
Time complexity: O(|V||V|), |V| is the number of vertices in the
graph.
* File examples/simple/igraph_adjacency.c*
File: igraph_reference_manual.info, Node: igraph_weighted_adjacency --- Creates a graph object from a weighted adjacency matrix_, Next: igraph_adjlist --- Create a graph from an adjacency list, Prev: igraph_adjacency --- Creates a graph object from an adjacency matrix_, Up: Deterministic Graph Generators
9.1.4 igraph_weighted_adjacency -- Creates a graph object from a weighted adjacency matrix.
-------------------------------------------------------------------------------------------
int igraph_weighted_adjacency(igraph_t *graph, igraph_matrix_t *adjmatrix,
igraph_adjacency_t mode, const char* attr,
igraph_bool_t loops);
The order of the vertices in the matrix is preserved, i.e. the vertex
corresponding to the first row/column will be vertex with id 0, the
next row is for vertex 1, etc.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`adjmatrix':
The weighted adjacency matrix. How it is interpreted depends on
the `mode' argument. The common feature is that edges with zero
weights are considered nonexistent (however, negative weights are
permitted).
`mode':
Constant to specify how the given matrix is interpreted as an
adjacency matrix. Possible values (A(i,j) is the element in row i
and column j in the adjacency matrix `adjmatrix'):
`IGRAPH_ADJ_DIRECTED'
the graph will be directed and an element gives the weight of
the edge between two vertices.
`IGRAPH_ADJ_UNDIRECTED'
this is the same as `IGRAPH_ADJ_MAX', for convenience.
`IGRAPH_ADJ_MAX'
undirected graph will be created and the weight of the edge
between vertices i and j is max(A(i,j), A(j,i)).
`IGRAPH_ADJ_MIN'
undirected graph will be created with edge weight min(A(i,j),
A(j,i)) between vertices i and j.
`IGRAPH_ADJ_PLUS '
undirected graph will be created with edge weight
A(i,j)+A(j,i) between vertices i and j.
`IGRAPH_ADJ_UPPER '
undirected graph will be created, only the upper right
triangle (including the diagonal) is used for the edge
weights.
`IGRAPH_ADJ_LOWER '
undirected graph will be created, only the lower left
triangle (including the diagonal) is used for the edge
weights.
`attr':
the name of the attribute that will store the edge weights. If
`NULL' , it will use `weight' as the attribute name.
`loops':
Logical scalar, whether to ignore the diagonal elements in the
adjacency matrix.
*Returns:. *
`'
Error code, `IGRAPH_NONSQUARE': non-square matrix.
Time complexity: O(|V||V|), |V| is the number of vertices in the
graph.
* File examples/simple/igraph_weighted_adjacency.c*
File: igraph_reference_manual.info, Node: igraph_adjlist --- Create a graph from an adjacency list, Next: igraph_star --- Creates a star graph; every vertex connects only to the center_, Prev: igraph_weighted_adjacency --- Creates a graph object from a weighted adjacency matrix_, Up: Deterministic Graph Generators
9.1.5 igraph_adjlist -- Create a graph from an adjacency list
-------------------------------------------------------------
int igraph_adjlist(igraph_t *graph, const igraph_adjlist_t *adjlist,
igraph_neimode_t mode, igraph_bool_t duplicate);
An adjacency list is a list of vectors, containing the neighbors of
all vertices. For operations that involve many changes to the graph
structure, it is recommended that you convert the graph into an
adjacency list via `igraph_adjlist_init()' (*note igraph_adjlist_init
--- Initialize an adjacency list of vertices from a given graph::),
perform the modifications (these are cheap for an adjacency list) and
then recreate the igraph graph via this function.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`adjlist':
The adjacency list.
`mode':
Whether or not to create a directed graph. `IGRAPH_ALL' means an
undirected graph, `IGRAPH_OUT' means a directed graph from an
out-adjacency list (i.e. each list contains the successors of the
corresponding vertices), `IGRAPH_IN' means a directed graph from an
in-adjacency list
`duplicate':
Logical, for undirected graphs this specified whether each edge is
included twice, in the vectors of both adjacent vertices. If this
is false (0), then it is assumed that every edge is included only
once. This argument is ignored for directed graphs.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_adjlist_init()' (*note igraph_adjlist_init --- Initialize
an adjacency list of vertices from a given graph::) for the
opposite operation.
Time complexity: O(|V|+|E|).
File: igraph_reference_manual.info, Node: igraph_star --- Creates a star graph; every vertex connects only to the center_, Next: igraph_lattice --- Creates most kinds of lattices_, Prev: igraph_adjlist --- Create a graph from an adjacency list, Up: Deterministic Graph Generators
9.1.6 igraph_star -- Creates a star graph, every vertex connects only to the center.
------------------------------------------------------------------------------------
int igraph_star(igraph_t *graph, igraph_integer_t n, igraph_star_mode_t mode,
igraph_integer_t center);
*Arguments:. *
`graph':
Pointer to an uninitialized graph object, this will be the result.
`n':
Integer constant, the number of vertices in the graph.
`mode':
Constant, gives the type of the star graph to create. Possible
values:
`IGRAPH_STAR_OUT'
directed star graph, edges point _from_ the center to the
other vertices.
`IGRAPH_STAR_IN'
directed star graph, edges point _to_ the center from the
other vertices.
`IGRAPH_STAR_MUTUAL'
directed star graph with mutual edges.
`IGRAPH_STAR_UNDIRECTED '
an undirected star graph is created.
`center':
Id of the vertex which will be the center of the graph.
*Returns:. *
`'
Error code:
`IGRAPH_EINVVID '
invalid number of vertices.
`IGRAPH_EINVAL '
invalid center vertex.
`IGRAPH_EINVMODE '
invalid mode argument.
Time complexity: O(|V|), the number of vertices in the graph.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::), `igraph_ring()' (*note igraph_ring --- Creates a
ring graph; a one dimensional lattice_::), `igraph_tree()' (*note
igraph_tree --- Creates a tree in which almost all vertices have
the same number of children_::) for creating other regular
structures.
* File examples/simple/igraph_star.c*
File: igraph_reference_manual.info, Node: igraph_lattice --- Creates most kinds of lattices_, Next: igraph_ring --- Creates a ring graph; a one dimensional lattice_, Prev: igraph_star --- Creates a star graph; every vertex connects only to the center_, Up: Deterministic Graph Generators
9.1.7 igraph_lattice -- Creates most kinds of lattices.
-------------------------------------------------------
int igraph_lattice(igraph_t *graph, const igraph_vector_t *dimvector,
igraph_integer_t nei, igraph_bool_t directed, igraph_bool_t mutual,
igraph_bool_t circular);
*Arguments:. *
`graph':
An uninitialized graph object.
`dimvector':
Vector giving the sizes of the lattice in each of its dimensions.
Ie. the dimension of the lattice will be the same as the length of
this vector.
`nei':
Integer value giving the distance (number of steps) within which
two vertices will be connected.
`directed':
Boolean, whether to create a directed graph. The direction of the
edges is determined by the generation algorithm and is unlikely to
suit you, so this isn't a very useful option.
`mutual':
Boolean, if the graph is directed this gives whether to create all
connections as mutual.
`circular':
Boolean, defines whether the generated lattice is periodic.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid (negative) dimension vector.
Time complexity: if `nei' is less than two then it is O(|V|+|E|) (as
far as I remember), |V| and |E| are the number of vertices and edges in
the generated graph. Otherwise it is O(|V|*d^o+|E|), d is the average
degree of the graph, o is the `nei' argument.
File: igraph_reference_manual.info, Node: igraph_ring --- Creates a ring graph; a one dimensional lattice_, Next: igraph_tree --- Creates a tree in which almost all vertices have the same number of children_, Prev: igraph_lattice --- Creates most kinds of lattices_, Up: Deterministic Graph Generators
9.1.8 igraph_ring -- Creates a ring graph, a one dimensional lattice.
---------------------------------------------------------------------
int igraph_ring(igraph_t *graph, igraph_integer_t n, igraph_bool_t directed,
igraph_bool_t mutual, igraph_bool_t circular);
An undirected (circular) ring on n vertices is commonly known in
graph theory as the cycle graph C_n.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
The number of vertices in the ring.
`directed':
Logical, whether to create a directed ring.
`mutual':
Logical, whether to create mutual edges in a directed ring. It is
ignored for undirected graphs.
`circular':
Logical, if false, the ring will be open (this is not a real
_ring_ actually).
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of vertices.
Time complexity: O(|V|), the number of vertices in the graph.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::) for generating more general lattices.
* File examples/simple/igraph_ring.c*
File: igraph_reference_manual.info, Node: igraph_tree --- Creates a tree in which almost all vertices have the same number of children_, Next: igraph_full --- Creates a full graph [directed or undirected; with or without loops]_, Prev: igraph_ring --- Creates a ring graph; a one dimensional lattice_, Up: Deterministic Graph Generators
9.1.9 igraph_tree -- Creates a tree in which almost all vertices have the same number of children.
--------------------------------------------------------------------------------------------------
int igraph_tree(igraph_t *graph, igraph_integer_t n, igraph_integer_t children,
igraph_tree_mode_t type);
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
Integer, the number of vertices in the graph.
`children':
Integer, the number of children of a vertex in the tree.
`type':
Constant, gives whether to create a directed tree, and if this is
the case, also its orientation. Possible values:
`IGRAPH_TREE_OUT '
directed tree, the edges point from the parents to their
children,
`IGRAPH_TREE_IN '
directed tree, the edges point from the children to their
parents.
`IGRAPH_TREE_UNDIRECTED'
undirected tree.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of vertices.
`IGRAPH_INVMODE': invalid mode argument.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::), `igraph_star()' (*note igraph_star --- Creates a
star graph; every vertex connects only to the center_::) for
creating other regular structures.
* File examples/simple/igraph_tree.c*
File: igraph_reference_manual.info, Node: igraph_full --- Creates a full graph [directed or undirected; with or without loops]_, Next: igraph_full_citation --- Creates a full citation graph, Prev: igraph_tree --- Creates a tree in which almost all vertices have the same number of children_, Up: Deterministic Graph Generators
9.1.10 igraph_full -- Creates a full graph (directed or undirected, with or without loops).
-------------------------------------------------------------------------------------------
int igraph_full(igraph_t *graph, igraph_integer_t n, igraph_bool_t directed,
igraph_bool_t loops);
In a full graph every possible edge is present, every vertex is
connected to every other vertex. A full graph in `igraph' should be
distinguished from the concept of complete graphs as used in graph
theory. If n is a positive integer, then the complete graph K_n on n
vertices is the undirected simple graph with the following property.
For any distinct pair (u,v) of vertices in K_n, uv (or equivalently vu)
is an edge of K_n. In `igraph', a full graph on n vertices can be K_n,
a directed version of K_n, or K_n with at least one loop edge. In any
case, if F is a full graph on n vertices as generated by `igraph', then
K_n is a subgraph of the undirected version of F.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
Integer, the number of vertices in the graph.
`directed':
Logical, whether to create a directed graph.
`loops':
Logical, whether to include self-edges (loops).
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid number of vertices.
Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| the
number of edges in the graph. Of course this is the same as
O(|E|)=O(|V||V|) here.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::), `igraph_star()' (*note igraph_star --- Creates a
star graph; every vertex connects only to the center_::),
`igraph_tree()' (*note igraph_tree --- Creates a tree in which
almost all vertices have the same number of children_::) for
creating other regular structures.
* File examples/simple/igraph_full.c*
File: igraph_reference_manual.info, Node: igraph_full_citation --- Creates a full citation graph, Next: igraph_famous --- Create a famous graph by simply providing its name, Prev: igraph_full --- Creates a full graph [directed or undirected; with or without loops]_, Up: Deterministic Graph Generators
9.1.11 igraph_full_citation -- Creates a full citation graph
------------------------------------------------------------
int igraph_full_citation(igraph_t *graph, igraph_integer_t n,
igraph_bool_t directed);
This is a directed graph, where every ` i->j' edge is present if
and only if ` j*1 and
n>2. The Chvatal graph is an example for m=4 and n=12. It has 24
edges.
`Coxeter '
A non-Hamiltonian cubic symmetric graph with 28 vertices and 42
edges.
`Cubical'
The Platonic graph of the cube. A convex regular polyhedron with 8
vertices and 12 edges.
`Diamond'
A graph with 4 vertices and 5 edges, resembles a schematic diamond
if drawn properly.
`Dodecahedral, Dodecahedron'
Another Platonic solid with 20 vertices and 30 edges.
`Folkman '
The semisymmetric graph with minimum number of vertices, 20 and 40
edges. A semisymmetric graph is regular, edge transitive and not
vertex transitive.
`Franklin '
This is a graph whose embedding to the Klein bottle can be colored
with six colors, it is a counterexample to the necessity of the
Heawood conjecture on a Klein bottle. It has 12 vertices and 18
edges.
`Frucht '
The Frucht Graph is the smallest cubical graph whose automorphism
group consists only of the identity element. It has 12 vertices
and 18 edges.
`Grotzsch '
The Gro"tzsch graph is a triangle-free graph with 11 vertices, 20
edges, and chromatic number 4. It is named after German
mathematician Herbert Gro"tzsch, and its existence demonstrates
that the assumption of planarity is necessary in Gro"tzsch's
theorem that every triangle-free planar graph is 3-colorable.
`Heawood '
The Heawood graph is an undirected graph with 14 vertices and 21
edges. The graph is cubic, and all cycles in the graph have six or
more edges. Every smaller cubic graph has shorter cycles, so this
graph is the 6-cage, the smallest cubic graph of girth 6.
`Herschel '
The Herschel graph is the smallest nonhamiltonian polyhedral
graph. It is the unique such graph on 11 nodes, and has 18 edges.
`House'
The house graph is a 5-vertex, 6-edge graph, the schematic draw of
a house if drawn properly, basically a triangle on top of a square.
`HouseX'
The same as the house graph with an X in the square. 5 vertices
and 8 edges.
`Icosahedral, Icosahedron '
A Platonic solid with 12 vertices and 30 edges.
`Krackhardt_Kite'
A social network with 10 vertices and 18 edges. Krackhardt, D.
Assessing the Political Landscape: Structure, Cognition, and Power
in Organizations. Admin. Sci. Quart. 35, 342-369, 1990.
`Levi '
The graph is a 4-arc transitive cubic graph, it has 30 vertices
and 45 edges.
`McGee '
The McGee graph is the unique 3-regular 7-cage graph, it has 24
vertices and 36 edges.
`Meredith '
The Meredith graph is a quartic graph on 70 nodes and 140 edges
that is a counterexample to the conjecture that every 4-regular
4-connected graph is Hamiltonian.
`Noperfectmatching '
A connected graph with 16 vertices and 27 edges containing no
perfect matching. A matching in a graph is a set of pairwise
non-incident edges; that is, no two edges share a common vertex. A
perfect matching is a matching which covers all vertices of the
graph.
`Nonline '
A graph whose connected components are the 9 graphs whose presence
as a vertex-induced subgraph in a graph makes a nonline graph. It
has 50 vertices and 72 edges.
`Octahedral, Octahedron '
Platonic solid with 6 vertices and 12 edges.
`Petersen'
A 3-regular graph with 10 vertices and 15 edges. It is the
smallest hypohamiltonian graph, ie. it is non-hamiltonian but
removing any single vertex from it makes it Hamiltonian.
`Robertson '
The unique (4,5)-cage graph, ie. a 4-regular graph of girth 5. It
has 19 vertices and 38 edges.
`Smallestcyclicgroup '
A smallest nontrivial graph whose automorphism group is cyclic. It
has 9 vertices and 15 edges.
`Tetrahedral, Tetrahedron '
Platonic solid with 4 vertices and 6 edges.
`Thomassen '
The smallest hypotraceable graph, on 34 vertices and 52 edges. A
hypotracable graph does not contain a Hamiltonian path but after
removing any single vertex from it the remainder always contains a
Hamiltonian path. A graph containing a Hamiltonian path is called
traceable.
`Tutte '
Tait's Hamiltonian graph conjecture states that every 3-connected
3-regular planar graph is Hamiltonian. This graph is a
counterexample. It has 46 vertices and 69 edges.
`Uniquely3colorable '
Returns a 12-vertex, triangle-free graph with chromatic number 3
that is uniquely 3-colorable.
`Walther '
An identity graph with 25 vertices and 31 edges. An identity graph
has a single graph automorphism, the trivial one.
`Zachary'
Social network of friendships between 34 members of a karate club
at a US university in the 1970s. See W. W. Zachary, An information
flow model for conflict and fission in small groups, Journal of
Anthropological Research 33, 452-473 (1977).
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`name':
Character constant, the name of the graph to be created, it is
case insensitive.
*Returns:. *
`'
Error code, IGRAPH_EINVAL if there is no graph with the given name.
*See also:. *
`'
Other functions for creating graph structures: `igraph_ring()'
(*note igraph_ring --- Creates a ring graph; a one dimensional
lattice_::), `igraph_tree()' (*note igraph_tree --- Creates a tree
in which almost all vertices have the same number of children_::),
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::), `igraph_full()' (*note igraph_full --- Creates a
full graph [directed or undirected; with or without loops]_::).
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_lcf --- Create a graph from LCF notation, Next: igraph_lcf_vector --- Create a graph from LCF notation, Prev: igraph_famous --- Create a famous graph by simply providing its name, Up: Deterministic Graph Generators
9.1.13 igraph_lcf -- Create a graph from LCF notation
-----------------------------------------------------
int igraph_lcf(igraph_t *graph, igraph_integer_t n, ...);
LCF is short for Lederberg-Coxeter-Frucht, it is a concise notation
for 3-regular Hamiltonian graphs. It consists of three parameters: the
number of vertices in the graph, a list of shifts giving additional
edges to a cycle backbone, and another integer giving how many times
the shifts should be performed. See
http://mathworld.wolfram.com/LCFNotation.html
(http://mathworld.wolfram.com/LCFNotation.html) for details.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
Integer, the number of vertices in the graph.
`...':
The shifts and the number of repeats for the shifts, plus an
additional 0 to mark the end of the arguments.
*Returns:. *
`'
Error code.
*See also:. *
`'
See `igraph_lcf_vector()' (*note igraph_lcf_vector --- Create a
graph from LCF notation::) for a similar function using a vector_t
instead of the variable length argument list.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_lcf.c*
File: igraph_reference_manual.info, Node: igraph_lcf_vector --- Create a graph from LCF notation, Next: igraph_atlas --- Create a small graph from the Graph Atlas_, Prev: igraph_lcf --- Create a graph from LCF notation, Up: Deterministic Graph Generators
9.1.14 igraph_lcf_vector -- Create a graph from LCF notation
------------------------------------------------------------
int igraph_lcf_vector(igraph_t *graph, igraph_integer_t n,
const igraph_vector_t *shifts,
igraph_integer_t repeats);
This function is essentially the same as `igraph_lcf()' (*note
igraph_lcf --- Create a graph from LCF notation::), only the way for
giving the arguments is different. See `igraph_lcf()' (*note igraph_lcf
--- Create a graph from LCF notation::) for details.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
Integer constant giving the number of vertices.
`shifts':
A vector giving the shifts.
`repeats':
An integer constant giving the number of repeats for the shifts.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_lcf()' (*note igraph_lcf --- Create a graph from LCF
notation::)
Time complexity: O(|V|+|E|), linear in the number of vertices plus
the number of edges.
File: igraph_reference_manual.info, Node: igraph_atlas --- Create a small graph from the Graph Atlas_, Next: igraph_de_bruijn --- Generate a de Bruijn graph_, Prev: igraph_lcf_vector --- Create a graph from LCF notation, Up: Deterministic Graph Generators
9.1.15 igraph_atlas -- Create a small graph from the Graph Atlas.
-----------------------------------------------------------------
int igraph_atlas(igraph_t *graph, int number);
The number of the graph is given as a parameter. The graphs are
listed:
1. in increasing order of number of nodes;
2. for a fixed number of nodes, in increasing order of the number of
edges;
3. for fixed numbers of nodes and edges, in increasing order of the
degree sequence, for example 111223 < 112222;
4. for fixed degree sequence, in increasing number of automorphisms.
The data was converted from the NetworkX software package, see
http://networkx.github.io (http://networkx.github.io) .
See _ An Atlas of Graphs _ by Ronald C. Read and Robin J. Wilson,
Oxford University Press, 1998.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`number':
The number of the graph to generate.
Added in version 0.2.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_atlas.c*
File: igraph_reference_manual.info, Node: igraph_de_bruijn --- Generate a de Bruijn graph_, Next: igraph_kautz --- Generate a Kautz graph_, Prev: igraph_atlas --- Create a small graph from the Graph Atlas_, Up: Deterministic Graph Generators
9.1.16 igraph_de_bruijn -- Generate a de Bruijn graph.
------------------------------------------------------
int igraph_de_bruijn(igraph_t *graph, igraph_integer_t m, igraph_integer_t n);
A de Bruijn graph represents relationships between strings. An
alphabet of `m' letters are used and strings of length `n' are
considered. A vertex corresponds to every possible string and there is
a directed edge from vertex `v' to vertex `w' if the string of `v' can
be transformed into the string of `w' by removing its first letter and
appending a letter to it.
Please note that the graph will have `m' to the power `n' vertices
and even more edges, so probably you don't want to supply too big
numbers for `m' and `n'.
De Bruijn graphs have some interesting properties, please see
another source, eg. Wikipedia for details.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object, the result will be
stored here.
`m':
Integer, the number of letters in the alphabet.
`n':
Integer, the length of the strings.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_kautz()' (*note igraph_kautz --- Generate a Kautz
graph_::).
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
File: igraph_reference_manual.info, Node: igraph_kautz --- Generate a Kautz graph_, Next: igraph_extended_chordal_ring --- Create an extended chordal ring, Prev: igraph_de_bruijn --- Generate a de Bruijn graph_, Up: Deterministic Graph Generators
9.1.17 igraph_kautz -- Generate a Kautz graph.
----------------------------------------------
int igraph_kautz(igraph_t *graph, igraph_integer_t m, igraph_integer_t n);
A Kautz graph is a labeled graph, vertices are labeled by strings of
length `n'+1 above an alphabet with `m'+1 letters, with the restriction
that every two consecutive letters in the string must be different.
There is a directed edge from a vertex `v' to another vertex `w' if it
is possible to transform the string of `v' into the string of `w' by
removing the first letter and appending a letter to it.
Kautz graphs have some interesting properties, see eg. Wikipedia for
details.
Vincent Matossian wrote the first version of this function in R,
thanks.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object, the result will be
stored here.
`m':
Integer, `m'+1 is the number of letters in the alphabet.
`n':
Integer, `n'+1 is the length of the strings.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_de_bruijn()' (*note igraph_de_bruijn --- Generate a de
Bruijn graph_::).
Time complexity: O(|V|* [(m+1)/m]^n +|E|), in practice it is more
like O(|V|+|E|). |V| is the number of vertices, |E| is the number of
edges and `m' and `n' are the corresponding arguments.
File: igraph_reference_manual.info, Node: igraph_extended_chordal_ring --- Create an extended chordal ring, Next: igraph_connect_neighborhood --- Connects every vertex to its neighborhood, Prev: igraph_kautz --- Generate a Kautz graph_, Up: Deterministic Graph Generators
9.1.18 igraph_extended_chordal_ring -- Create an extended chordal ring
----------------------------------------------------------------------
int igraph_extended_chordal_ring(igraph_t *graph, igraph_integer_t nodes,
const igraph_matrix_t *W);
An extended chordal ring is a regular graph, each node has the same
degree. It can be obtained from a simple ring by adding some extra
edges specified by a matrix. Let p denote the number of columns in the
`W' matrix. The extra edges of vertex i are added according to column
(i mod p) in `W'. The number of extra edges is the number of rows in
`W': for each row j an edge i->i+w[ij] is added if i+w[ij] is less than
the number of total nodes.
See also Kotsis, G: Interconnection Topologies for Parallel
Processing Systems, PARS Mitteilungen 11, 1-6, 1993.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object, the result will be
stored here. The result is always an undirected graph.
`nodes':
Integer constant, the number of vertices in the graph. It must be
at least 3.
`W':
The matrix specifying the extra edges. The number of columns
should divide the number of total vertices.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ring()' (*note igraph_ring --- Creates a ring graph; a one
dimensional lattice_::).
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
File: igraph_reference_manual.info, Node: igraph_connect_neighborhood --- Connects every vertex to its neighborhood, Prev: igraph_extended_chordal_ring --- Create an extended chordal ring, Up: Deterministic Graph Generators
9.1.19 igraph_connect_neighborhood -- Connects every vertex to its neighborhood
-------------------------------------------------------------------------------
int igraph_connect_neighborhood(igraph_t *graph, igraph_integer_t order,
igraph_neimode_t mode);
This function adds new edges to the input graph. For each vertex
vertices reachable by at most `order' steps and not yet connected to
the vertex a new edge is created.
Note that the input graph is modified in place, no new graph is
created, call `igraph_copy()' (*note igraph_copy --- Creates an exact
[deep] copy of a graph_::) if you want to keep the original graph as
well.
For undirected graphs reachability is always symmetric: if vertex A
can be reached from vertex B in at most `order' steps, then the
opposite is also true. Only one undirected (A,B) edge will be added in
this case.
*Arguments:. *
`graph':
The input graph, this is the output graph as well.
`order':
Integer constant, it gives the distance within which the vertices
will be connected to the source vertex.
`mode':
Constant, it specifies how the neighborhood search is performed
for directed graphs. If `IGRAPH_OUT' then vertices reachable from
the source vertex will be connected, `IGRAPH_IN' is the opposite.
If `IGRAPH_ALL' then the directed graph is considered as an
undirected one.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::) uses this function to connect the neighborhood of the
vertices.
Time complexity: O(|V|*d^o), |V| is the number of vertices in the
graph, d is the average degree and o is the `order' argument.
File: igraph_reference_manual.info, Node: Games; Randomized Graph Generators, Prev: Deterministic Graph Generators, Up: Graph Generators
9.2 Games: Randomized Graph Generators
======================================
Games are randomized graph generators. Randomization means that they
generate a different graph every time you call them.
* Menu:
* igraph_grg_game --- Generating geometric random graphs.: igraph_grg_game --- Generating geometric random graphs_.
* igraph_barabasi_game --- Generates a graph based on the Baraba'si-Albert model.: igraph_barabasi_game --- Generates a graph based on the Baraba'si-Albert model_.
* igraph_erdos_renyi_game --- Generates a random (Erdos-Renyi) graph.: igraph_erdos_renyi_game --- Generates a random [Erdos-Renyi] graph_.
* igraph_watts_strogatz_game --- The Watts-Strogatz small-world model::
* igraph_rewire_edges --- Rewire the edges of a graph with constant probability::
* igraph_degree_sequence_game --- Generates a random graph with a given degree sequence : igraph_degree_sequence_game --- Generates a random graph with a given degree sequence.
* igraph_k_regular_game --- Generates a random graph where each vertex has the same degree.: igraph_k_regular_game --- Generates a random graph where each vertex has the same degree_.
* igraph_static_fitness_game --- Generates a non-growing random graph with edge probabilities::
* igraph_static_power_law_game --- Generates a non-growing random graph with expected power-law degree distributions.: igraph_static_power_law_game --- Generates a non-growing random graph with expected power-law degree distributions_.
* igraph_forest_fire_game --- Generates a network according to the forest fire game::
* igraph_rewire --- Randomly rewires a graph while preserving the degree distribution.: igraph_rewire --- Randomly rewires a graph while preserving the degree distribution_.
* igraph_growing_random_game --- Generates a growing random graph.: igraph_growing_random_game --- Generates a growing random graph_.
* igraph_callaway_traits_game --- Simulate a growing network with vertex types.: igraph_callaway_traits_game --- Simulate a growing network with vertex types_.
* igraph_establishment_game --- Generates a graph with a simple growing model with vertex types.: igraph_establishment_game --- Generates a graph with a simple growing model with vertex types_.
* igraph_preference_game --- Generates a graph with vertex types and connection preferences : igraph_preference_game --- Generates a graph with vertex types and connection preferences.
* igraph_asymmetric_preference_game --- Generates a graph with asymmetric vertex types and connection preferences : igraph_asymmetric_preference_game --- Generates a graph with asymmetric vertex types and connection preferences.
* igraph_recent_degree_game --- Stochastic graph generator based on the number of incident edges a node has gained recently::
* igraph_barabasi_aging_game --- Preferential attachment with aging of vertices::
* igraph_recent_degree_aging_game --- Preferential attachment based on the number of edges gained recently, with aging of vertices: igraph_recent_degree_aging_game --- Preferential attachment based on the number of edges gained recently; with aging of vertices.
* igraph_cited_type_game --- Simulate a citation based on vertex types.: igraph_cited_type_game --- Simulate a citation based on vertex types_.
* igraph_citing_cited_type_game --- Simulate a citation network based on vertex types.: igraph_citing_cited_type_game --- Simulate a citation network based on vertex types_.
* igraph_sbm_game --- Sample from a stochastic block model::
File: igraph_reference_manual.info, Node: igraph_grg_game --- Generating geometric random graphs_, Next: igraph_barabasi_game --- Generates a graph based on the Baraba'si-Albert model_, Up: Games; Randomized Graph Generators
9.2.1 igraph_grg_game -- Generating geometric random graphs.
------------------------------------------------------------
int igraph_grg_game(igraph_t *graph, igraph_integer_t nodes,
igraph_real_t radius, igraph_bool_t torus,
igraph_vector_t *x, igraph_vector_t *y);
A geometric random graph is created by dropping points (=vertices)
randomly to the unit square and then connecting all those pairs which
are less than `radius' apart in Euclidean norm.
Original code contributed by Keith Briggs, thanks Keith.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object,
`nodes':
The number of vertices in the graph.
`radius':
The radius within which the vertices will be connected.
`torus':
Logical constant, if true periodic boundary conditions will be
used, ie. the vertices are assumed to be on a torus instead of a
square.
*Returns:. *
`'
Error code.
Time complexity: TODO, less than O(|V|^2+|E|).
* File examples/simple/igraph_grg_game.c*
File: igraph_reference_manual.info, Node: igraph_barabasi_game --- Generates a graph based on the Baraba'si-Albert model_, Next: igraph_erdos_renyi_game --- Generates a random [Erdos-Renyi] graph_, Prev: igraph_grg_game --- Generating geometric random graphs_, Up: Games; Randomized Graph Generators
9.2.2 igraph_barabasi_game -- Generates a graph based on the Baraba'si-Albert model.
------------------------------------------------------------------------------------
int igraph_barabasi_game(igraph_t *graph, igraph_integer_t n,
igraph_real_t power,
igraph_integer_t m,
const igraph_vector_t *outseq,
igraph_bool_t outpref,
igraph_real_t A,
igraph_bool_t directed,
igraph_barabasi_algorithm_t algo,
const igraph_t *start_from);
*Arguments:. *
`graph':
An uninitialized graph object.
`n':
The number of vertices in the graph.
`power':
Power of the preferential attachment. The probability that a
vertex is cited is proportional to d^power+A, where d is its
degree (see also the `outpref' argument), power and A are given by
arguments. In the classic preferential attachment model power=1.
`m':
The number of outgoing edges generated for each vertex. (Only if
`outseq' is `NULL'.)
`outseq':
Gives the (out-)degrees of the vertices. If this is constant, this
can be a NULL pointer or an empty (but initialized!) vector, in
this case `m' contains the constant out-degree. The very first
vertex has by definition no outgoing edges, so the first number in
this vector is ignored.
`outpref':
Boolean, if true not only the in- but also the out-degree of a
vertex increases its citation probability. Ie. the citation
probability is determined by the total degree of the vertices.
`A':
The probability that a vertex is cited is proportional to
d^power+A, where d is its degree (see also the `outpref'
argument), power and A are given by arguments. In the previous
versions of the function this parameter was implicitly set to one.
`directed':
Boolean, whether to generate a directed graph.
`algo':
The algorithm to use to generate the network. Possible values:
`IGRAPH_BARABASI_BAG'
This is the algorithm that was previously (before version
0.6) solely implemented in igraph. It works by putting the
ids of the vertices into a bag (multiset, really), exactly as
many times as their (in-)degree, plus once more. Then the
required number of cited vertices are drawn from the bag,
with replacement. This method might generate multiple edges.
It only works if power=1 and A=1.
`IGRAPH_BARABASI_PSUMTREE'
This algorithm uses a partial prefix-sum tree to generate the
graph. It does not generate multiple edges and works for any
power and A values.
`IGRAPH_BARABASI_PSUMTREE_MULTIPLE'
This algorithm also uses a partial prefix-sum tree to
generate the graph. The difference is, that now multiple
edges are allowed. This method was implemented under the name
`igraph_nonlinear_barabasi_game' before version 0.6.
`start_from':
Either a null pointer, or a graph. In the latter case the graph as
a starting configuration. The graph must be non-empty, i.e. it
must have at least one vertex. If a graph is supplied here and the
`outseq' argument is also given, then `outseq' should only contain
information on the vertices that are not in the `start_from' graph.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid `n', `m' or `outseq'
parameter.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_barabasi_game.c*
* File examples/simple/igraph_barabasi_game2.c*
File: igraph_reference_manual.info, Node: igraph_erdos_renyi_game --- Generates a random [Erdos-Renyi] graph_, Next: igraph_watts_strogatz_game --- The Watts-Strogatz small-world model, Prev: igraph_barabasi_game --- Generates a graph based on the Baraba'si-Albert model_, Up: Games; Randomized Graph Generators
9.2.3 igraph_erdos_renyi_game -- Generates a random (Erdos-Renyi) graph.
------------------------------------------------------------------------
int igraph_erdos_renyi_game(igraph_t *graph, igraph_erdos_renyi_t type,
igraph_integer_t n, igraph_real_t p_or_m,
igraph_bool_t directed, igraph_bool_t loops);
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`type':
The type of the random graph, possible values:
`IGRAPH_ERDOS_RENYI_GNM'
G(n,m) graph, m edges are selected uniformly randomly in a
graph with n vertices.
`IGRAPH_ERDOS_RENYI_GNP'
G(n,p) graph, every possible edge is included in the graph
with probability p.
`n':
The number of vertices in the graph.
`p_or_m':
This is the p parameter for G(n,p) graphs and the m parameter for
G(n,m) graphs.
`directed':
Logical, whether to generate a directed graph.
`loops':
Logical, whether to generate loops (self) edges.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid `type', `n', `p' or `m'
parameter. `IGRAPH_ENOMEM': there is not enough memory for the
operation.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
*See also:. *
`'
`igraph_barabasi_game()' (*note igraph_barabasi_game --- Generates
a graph based on the Baraba'si-Albert model_::),
`igraph_growing_random_game()' (*note igraph_growing_random_game
--- Generates a growing random graph_::)
* File examples/simple/igraph_erdos_renyi_game.c*
File: igraph_reference_manual.info, Node: igraph_watts_strogatz_game --- The Watts-Strogatz small-world model, Next: igraph_rewire_edges --- Rewire the edges of a graph with constant probability, Prev: igraph_erdos_renyi_game --- Generates a random [Erdos-Renyi] graph_, Up: Games; Randomized Graph Generators
9.2.4 igraph_watts_strogatz_game -- The Watts-Strogatz small-world model
------------------------------------------------------------------------
int igraph_watts_strogatz_game(igraph_t *graph, igraph_integer_t dim,
igraph_integer_t size, igraph_integer_t nei,
igraph_real_t p, igraph_bool_t loops,
igraph_bool_t multiple);
This function generates a graph according to the Watts-Strogatz
model of small-world networks. The graph is obtained by creating a
circular undirected lattice and then rewire the edges randomly with a
constant probability.
See also: Duncan J Watts and Steven H Strogatz: Collective dynamics
of `small world' networks, Nature 393, 440-442, 1998.
*Arguments:. *
`graph':
The graph to initialize.
`dim':
The dimension of the lattice.
`size':
The size of the lattice along each dimension.
`nei':
The size of the neighborhood for each vertex. This is the same as
the `nei' argument of `igraph_connect_neighborhood()' (*note
igraph_connect_neighborhood --- Connects every vertex to its
neighborhood::).
`p':
The rewiring probability. A real number between zero and one
(inclusive).
`loops':
Logical, whether to generate loop edges.
`multiple':
Logical, whether to allow multiple edges in the generated graph.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_lattice()' (*note igraph_lattice --- Creates most kinds of
lattices_::), `igraph_connect_neighborhood()' (*note
igraph_connect_neighborhood --- Connects every vertex to its
neighborhood::) and `igraph_rewire_edges()' (*note
igraph_rewire_edges --- Rewire the edges of a graph with constant
probability::) can be used if more flexibility is needed, eg. a
different type of lattice.
Time complexity: O(|V|*d^o+|E|), |V| and |E| are the number of
vertices and edges, d is the average degree, o is the `nei' argument.
File: igraph_reference_manual.info, Node: igraph_rewire_edges --- Rewire the edges of a graph with constant probability, Next: igraph_degree_sequence_game --- Generates a random graph with a given degree sequence, Prev: igraph_watts_strogatz_game --- The Watts-Strogatz small-world model, Up: Games; Randomized Graph Generators
9.2.5 igraph_rewire_edges -- Rewire the edges of a graph with constant probability
----------------------------------------------------------------------------------
int igraph_rewire_edges(igraph_t *graph, igraph_real_t prob,
igraph_bool_t loops, igraph_bool_t multiple);
This function rewires the edges of a graph with a constant
probability. More precisely each end point of each edge is rewired to a
uniformly randomly chosen vertex with constant probability `prob'.
Note that this function modifies the input `graph', call
`igraph_copy()' (*note igraph_copy --- Creates an exact [deep] copy of
a graph_::) if you want to keep it.
*Arguments:. *
`graph':
The input graph, this will be rewired, it can be directed or
undirected.
`prob':
The rewiring probability a constant between zero and one
(inclusive).
`loops':
Boolean, whether loop edges are allowed in the new graph, or not.
`multiple':
Boolean, whether multiple edges are allowed in the new graph.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_watts_strogatz_game()' (*note igraph_watts_strogatz_game
--- The Watts-Strogatz small-world model::) uses this function for
the rewiring.
Time complexity: O(|V|+|E|).
File: igraph_reference_manual.info, Node: igraph_degree_sequence_game --- Generates a random graph with a given degree sequence, Next: igraph_k_regular_game --- Generates a random graph where each vertex has the same degree_, Prev: igraph_rewire_edges --- Rewire the edges of a graph with constant probability, Up: Games; Randomized Graph Generators
9.2.6 igraph_degree_sequence_game -- Generates a random graph with a given degree sequence
------------------------------------------------------------------------------------------
int igraph_degree_sequence_game(igraph_t *graph, const igraph_vector_t *out_deg,
const igraph_vector_t *in_deg,
igraph_degseq_t method);
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`out_deg':
The degree sequence for an undirected graph (if `in_seq' is of
length zero), or the out-degree sequence of a directed graph (if
`in_deq' is not of length zero.
`in_deg':
It is either a zero-length vector or `NULL' (if an undirected
graph is generated), or the in-degree sequence.
`method':
The method to generate the graph. Possible values:
`IGRAPH_DEGSEQ_SIMPLE'
For undirected graphs, this method puts all vertex ids in a
bag such that the multiplicity of a vertex in the bag is the
same as its degree. Then it draws pairs from the bag until
the bag becomes empty. This method can generate both loop
(self) edges and multiple edges. For directed graphs, the
algorithm is basically the same, but two separate bags are
used for the in- and out-degrees.
`IGRAPH_DEGSEQ_SIMPLE_NO_MULTIPLE'
This method is similar to `IGRAPH_DEGSEQ_SIMPLE' but tries to
avoid multiple and loop edges and restarts the generation
from scratch if it gets stuck. It is not guaranteed to sample
uniformly from the space of all possible graphs with the
given sequence, but it is relatively fast and it will
eventually succeed if the provided degree sequence is
graphical, but there is no upper bound on the number of
iterations.
`IGRAPH_DEGSEQ_VL'
This method is a much more sophisticated generator than the
previous ones. It can sample undirected, connected simple
graphs uniformly and uses Monte-Carlo methods to randomize
the graphs. This generator should be favoured if undirected
and connected graphs are to be generated and execution time
is not a concern. igraph uses the original implementation of
Fabien Viger; see
http://www-rp.lip6.fr/~latapy/FV/generation.html
(http://www-rp.lip6.fr/~latapy/FV/generation.html) and the
paper cited on it for the details of the algorithm.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM': there is not enough memory to perform
the operation. `IGRAPH_EINVAL': invalid method parameter, or
invalid in- and/or out-degree vectors. The degree vectors should
be non-negative, `out_deg' should sum up to an even integer for
undirected graphs; the length and sum of `out_deg' and `in_deg'
should match for directed graphs.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges for `IGRAPH_DEGSEQ_SIMPLE'. The time complexity of the other
modes is not known.
*See also:. *
`'
`igraph_barabasi_game()' (*note igraph_barabasi_game --- Generates
a graph based on the Baraba'si-Albert model_::),
`igraph_erdos_renyi_game()' (*note igraph_erdos_renyi_game ---
Generates a random [Erdos-Renyi] graph_::),
`igraph_is_degree_sequence()' (*note igraph_is_degree_sequence ---
Determines whether a degree sequence is valid_::),
`igraph_is_graphical_degree_sequence()' (*note
igraph_is_graphical_degree_sequence --- Determines whether a
sequence of integers can be a degree sequence of some::)
* File examples/simple/igraph_degree_sequence_game.c*
File: igraph_reference_manual.info, Node: igraph_k_regular_game --- Generates a random graph where each vertex has the same degree_, Next: igraph_static_fitness_game --- Generates a non-growing random graph with edge probabilities, Prev: igraph_degree_sequence_game --- Generates a random graph with a given degree sequence, Up: Games; Randomized Graph Generators
9.2.7 igraph_k_regular_game -- Generates a random graph where each vertex has the same degree.
----------------------------------------------------------------------------------------------
int igraph_k_regular_game(igraph_t *graph,
igraph_integer_t no_of_nodes, igraph_integer_t k,
igraph_bool_t directed, igraph_bool_t multiple);
This game generates a directed or undirected random graph where the
degrees of vertices are equal to a predefined constant k. For undirected
graphs, at least one of k and the number of vertices must be even.
The game simply uses `igraph_degree_sequence_game' (*note
igraph_degree_sequence_game --- Generates a random graph with a given
degree sequence::) with appropriately constructed degree sequences.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`no_of_nodes':
The number of nodes in the generated graph.
`k':
The degree of each vertex in an undirected graph, or the
out-degree and in-degree of each vertex in a directed graph.
`directed':
Whether the generated graph will be directed.
`multiple':
Whether to allow multiple edges in the generated graph.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid parameter; e.g., negative
number of nodes, or odd number of nodes and odd k for undirected
graphs. `IGRAPH_ENOMEM': there is not enough memory for the
operation.
Time complexity: O(|V|+|E|) if `multiple' is true, otherwise not
known.
File: igraph_reference_manual.info, Node: igraph_static_fitness_game --- Generates a non-growing random graph with edge probabilities, Next: igraph_static_power_law_game --- Generates a non-growing random graph with expected power-law degree distributions_, Prev: igraph_k_regular_game --- Generates a random graph where each vertex has the same degree_, Up: Games; Randomized Graph Generators
9.2.8 igraph_static_fitness_game -- Generates a non-growing random graph with edge probabilities
------------------------------------------------------------------------------------------------
int igraph_static_fitness_game(igraph_t *graph, igraph_integer_t no_of_edges,
igraph_vector_t* fitness_out, igraph_vector_t* fitness_in,
igraph_bool_t loops, igraph_bool_t multiple);
proportional to node fitness scores. This game generates a directed
or undirected random graph where the probability of an edge between
vertices i and j depends on the fitness scores of the two vertices
involved. For undirected graphs, each vertex has a single fitness
score. For directed graphs, each vertex has an out- and an in-fitness,
and the probability of an edge from i to j depends on the out-fitness
of vertex i and the in-fitness of vertex j.
The generation process goes as follows. We start from N disconnected
nodes (where N is given by the length of the fitness vector). Then we
randomly select two vertices i and j, with probabilities proportional
to their fitnesses. (When the generated graph is directed, i is
selected according to the out-fitnesses and j is selected according to
the in-fitnesses). If the vertices are not connected yet (or if
multiple edges are allowed), we connect them; otherwise we select a new
pair. This is repeated until the desired number of links are created.
It can be shown that the _expected_ degree of each vertex will be
proportional to its fitness, although the actual, observed degree will
not be. If you need to generate a graph with an exact degree sequence,
consider `igraph_degree_sequence_game' (*note
igraph_degree_sequence_game --- Generates a random graph with a given
degree sequence::) instead.
This model is commonly used to generate static scale-free networks.
To achieve this, you have to draw the fitness scores from the desired
power-law distribution. Alternatively, you may use
`igraph_static_power_law_game' (*note igraph_static_power_law_game ---
Generates a non-growing random graph with expected power-law degree
distributions_::) which generates the fitnesses for you with a given
exponent.
Reference: Goh K-I, Kahng B, Kim D: Universal behaviour of load
distribution in scale-free networks. Phys Rev Lett 87(27):278701, 2001.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`fitness_out':
A numeric vector containing the fitness of each vertex. For
directed graphs, this specifies the out-fitness of each vertex.
`fitness_in':
If `NULL', the generated graph will be undirected. If not `NULL',
this argument specifies the in-fitness of each vertex.
`no_of_edges':
The number of edges in the generated graph.
`loops':
Whether to allow loop edges in the generated graph.
`multiple':
Whether to allow multiple edges in the generated graph.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid parameter `IGRAPH_ENOMEM':
there is not enough memory for the operation.
Time complexity: O(|V| + |E| log |E|).
File: igraph_reference_manual.info, Node: igraph_static_power_law_game --- Generates a non-growing random graph with expected power-law degree distributions_, Next: igraph_forest_fire_game --- Generates a network according to the forest fire game, Prev: igraph_static_fitness_game --- Generates a non-growing random graph with edge probabilities, Up: Games; Randomized Graph Generators
9.2.9 igraph_static_power_law_game -- Generates a non-growing random graph with expected power-law degree distributions.
------------------------------------------------------------------------------------------------------------------------
int igraph_static_power_law_game(igraph_t *graph,
igraph_integer_t no_of_nodes, igraph_integer_t no_of_edges,
igraph_real_t exponent_out, igraph_real_t exponent_in,
igraph_bool_t loops, igraph_bool_t multiple,
igraph_bool_t finite_size_correction);
This game generates a directed or undirected random graph where the
degrees of vertices follow power-law distributions with prescribed
exponents. For directed graphs, the exponents of the in- and out-degree
distributions may be specified separately.
The game simply uses `igraph_static_fitness_game' (*note
igraph_static_fitness_game --- Generates a non-growing random graph
with edge probabilities::) with appropriately constructed fitness
vectors. In particular, the fitness of vertex i is i^-alpha, where
alpha = 1/(gamma-1) and gamma is the exponent given in the arguments.
To remove correlations between in- and out-degrees in case of
directed graphs, the in-fitness vector will be shuffled after it has
been set up and before `igraph_static_fitness_game' (*note
igraph_static_fitness_game --- Generates a non-growing random graph
with edge probabilities::) is called.
Note that significant finite size effects may be observed for
exponents smaller than 3 in the original formulation of the game. This
function provides an argument that lets you remove the finite size
effects by assuming that the fitness of vertex i is (i+i0-1)^-alpha,
where i0 is a constant chosen appropriately to ensure that the maximum
degree is less than the square root of the number of edges times the
average degree; see the paper of Chung and Lu, and Cho et al for more
details.
References:
Goh K-I, Kahng B, Kim D: Universal behaviour of load distribution in
scale-free networks. Phys Rev Lett 87(27):278701, 2001.
Chung F and Lu L: Connected components in a random graph with given
degree sequences. Annals of Combinatorics 6, 125-145, 2002.
Cho YS, Kim JS, Park J, Kahng B, Kim D: Percolation transitions in
scale-free networks under the Achlioptas process. Phys Rev Lett
103:135702, 2009.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`no_of_nodes':
The number of nodes in the generated graph.
`no_of_edges':
The number of edges in the generated graph.
`exponent_out':
The power law exponent of the degree distribution. For directed
graphs, this specifies the exponent of the out-degree
distribution. It must be greater than or equal to 2. If you pass
`IGRAPH_INFINITY' here, you will get back an Erdos-Renyi random
network.
`exponent_in':
If negative, the generated graph will be undirected. If greater
than or equal to 2, this argument specifies the exponent of the
in-degree distribution. If non-negative but less than 2, an error
will be generated.
`loops':
Whether to allow loop edges in the generated graph.
`multiple':
Whether to allow multiple edges in the generated graph.
`finite_size_correction':
Whether to use the proposed finite size correction of Cho et al.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid parameter `IGRAPH_ENOMEM':
there is not enough memory for the operation.
Time complexity: O(|V| + |E| log |E|).
File: igraph_reference_manual.info, Node: igraph_forest_fire_game --- Generates a network according to the forest fire game, Next: igraph_rewire --- Randomly rewires a graph while preserving the degree distribution_, Prev: igraph_static_power_law_game --- Generates a non-growing random graph with expected power-law degree distributions_, Up: Games; Randomized Graph Generators
9.2.10 igraph_forest_fire_game -- Generates a network according to the forest fire game
---------------------------------------------------------------------------------------
int igraph_forest_fire_game(igraph_t *graph, igraph_integer_t nodes,
igraph_real_t fw_prob, igraph_real_t bw_factor,
igraph_integer_t pambs, igraph_bool_t directed);
The forest fire model intends to reproduce the following network
characteristics, observed in real networks:
* Heavy-tailed in-degree distribution.
* Heavy-tailed out-degree distribution.
* Communities.
* Densification power-law. The network is densifying in time,
according to a power-law rule.
* Shrinking diameter. The diameter of the network decreases in time.
The network is generated in the following way. One vertex is added at
a time. This vertex connects to (cites) ` ambs' vertices already
present in the network, chosen uniformly random. Now, for each cited
vertex ` v' we do the following procedure:
1. We generate two random number, ` x' and ` y' , that are
geometrically distributed with means ` p/(1-p)' and ` rp(1-rp)' .
(` p' is ` fw_prob' , ` r' is ` bw_factor' .) The new vertex
cites ` x' outgoing neighbors and ` y' incoming neighbors of `
v' , from those which are not yet cited by the new vertex. If
there are less than ` x' or ` y' such vertices available then we
cite all of them.
2. The same procedure is applied to all the newly cited vertices.
See also: Jure Leskovec, Jon Kleinberg and Christos Faloutsos.
Graphs over time: densification laws, shrinking diameters and possible
explanations. _ KDD '05: Proceeding of the eleventh ACM SIGKDD
international conference on Knowledge discovery in data mining _,
177-187, 2005.
Note however, that the version of the model in the published paper
is incorrect in the sense that it cannot generate the kind of graphs
the authors claim. A corrected version is available from
http://cs.stanford.edu/people/jure/pubs/powergrowth-tkdd.pdf
(http://cs.stanford.edu/people/jure/pubs/powergrowth-tkdd.pdf) , our
implementation is based on this.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`nodes':
The number of vertices in the graph.
`fw_prob':
The forward burning probability.
`bw_factor':
The backward burning ratio. The backward burning probability is
calculated as ` bw.factor*fw.prob' .
`pambs':
The number of ambassador vertices.
`directed':
Whether to create a directed graph.
*Returns:. *
`'
Error code.
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_rewire --- Randomly rewires a graph while preserving the degree distribution_, Next: igraph_growing_random_game --- Generates a growing random graph_, Prev: igraph_forest_fire_game --- Generates a network according to the forest fire game, Up: Games; Randomized Graph Generators
9.2.11 igraph_rewire -- Randomly rewires a graph while preserving the degree distribution.
------------------------------------------------------------------------------------------
int igraph_rewire(igraph_t *graph, igraph_integer_t n, igraph_rewiring_t mode);
This function generates a new graph based on the original one by
randomly rewiring edges while preserving the original graph's degree
distribution. Please note that the rewiring is done "in place", so no
new graph will be allocated. If you would like to keep the original
graph intact, use `igraph_copy()' (*note igraph_copy --- Creates an
exact [deep] copy of a graph_::) beforehand.
*Arguments:. *
`graph':
The graph object to be rewired.
`n':
Number of rewiring trials to perform.
`mode':
The rewiring algorithm to be used. It can be one of the following:
`IGRAPH_REWIRING_SIMPLE'
Simple rewiring algorithm which chooses two arbitrary edges
in each step (namely (a,b) and (c,d)) and substitutes them
with (a,d) and (c,b) if they don't exist. The method will
neither destroy nor create self-loops.
`IGRAPH_REWIRING_SIMPLE_LOOPS'
Same as `IGRAPH_REWIRING_SIMPLE' but allows the creation or
destruction of self-loops.
*Returns:. *
`'
Error code:
`IGRAPH_EINVMODE'
Invalid rewiring mode.
`IGRAPH_EINVAL'
Graph unsuitable for rewiring (e.g. it has less than 4 nodes
in case of `IGRAPH_REWIRING_SIMPLE')
`IGRAPH_ENOMEM'
Not enough memory for temporary data.
Time complexity: TODO.
* File examples/simple/igraph_rewire.c*
File: igraph_reference_manual.info, Node: igraph_growing_random_game --- Generates a growing random graph_, Next: igraph_callaway_traits_game --- Simulate a growing network with vertex types_, Prev: igraph_rewire --- Randomly rewires a graph while preserving the degree distribution_, Up: Games; Randomized Graph Generators
9.2.12 igraph_growing_random_game -- Generates a growing random graph.
----------------------------------------------------------------------
int igraph_growing_random_game(igraph_t *graph, igraph_integer_t n,
igraph_integer_t m, igraph_bool_t directed,
igraph_bool_t citation);
This function simulates a growing random graph. In each discrete
time step a new vertex is added and a number of new edges are also
added. These graphs are known to be different from standard (not
growing) random graphs.
*Arguments:. *
`graph':
Uninitialized graph object.
`n':
The number of vertices in the graph.
`m':
The number of edges to add in a time step (ie. after adding a
vertex).
`directed':
Boolean, whether to generate a directed graph.
`citation':
Boolean, if `TRUE', the edges always originate from the most
recently added vertex.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid `n' or `m' parameter.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_growing_random_game.c*
File: igraph_reference_manual.info, Node: igraph_callaway_traits_game --- Simulate a growing network with vertex types_, Next: igraph_establishment_game --- Generates a graph with a simple growing model with vertex types_, Prev: igraph_growing_random_game --- Generates a growing random graph_, Up: Games; Randomized Graph Generators
9.2.13 igraph_callaway_traits_game -- Simulate a growing network with vertex types.
-----------------------------------------------------------------------------------
int igraph_callaway_traits_game (igraph_t *graph, igraph_integer_t nodes,
igraph_integer_t types, igraph_integer_t edges_per_step,
igraph_vector_t *type_dist,
igraph_matrix_t *pref_matrix,
igraph_bool_t directed);
The different types of vertices prefer to connect other types of
vertices with a given probability.
The simulation goes like this: in each discrete time step a new
vertex is added to the graph. The type of this vertex is generated
based on `type_dist'. Then two vertices are selected uniformly randomly
from the graph. The probability that they will be connected depends on
the types of these vertices and is taken from `pref_matrix'. Then
another two vertices are selected and this is repeated `edges_per_step'
times in each time step.
*Arguments:. *
`graph':
Pointer to an uninitialized graph.
`nodes':
The number of nodes in the graph.
`types':
Number of node types.
`edges_per_step':
The number of edges to be add per time step.
`type_dist':
Vector giving the distribution of the vertex types.
`pref_matrix':
Matrix giving the connection probabilities for the vertex types.
`directed':
Logical, whether to generate a directed graph.
*Returns:. *
`'
Error code.
Added in version 0.2.
Time complexity: O(|V|e*log(|V|)), |V| is the number of vertices, e
is `edges_per_step'.
File: igraph_reference_manual.info, Node: igraph_establishment_game --- Generates a graph with a simple growing model with vertex types_, Next: igraph_preference_game --- Generates a graph with vertex types and connection preferences, Prev: igraph_callaway_traits_game --- Simulate a growing network with vertex types_, Up: Games; Randomized Graph Generators
9.2.14 igraph_establishment_game -- Generates a graph with a simple growing model with vertex types.
----------------------------------------------------------------------------------------------------
int igraph_establishment_game(igraph_t *graph, igraph_integer_t nodes,
igraph_integer_t types, igraph_integer_t k,
igraph_vector_t *type_dist,
igraph_matrix_t *pref_matrix,
igraph_bool_t directed);
The simulation goes like this: a single vertex is added at each time
step. This new vertex tries to connect to `k' vertices in the graph.
The probability that such a connection is realized depends on the types
of the vertices involved.
*Arguments:. *
`graph':
Pointer to an uninitialized graph.
`nodes':
The number of vertices in the graph.
`types':
The number of vertex types.
`k':
The number of connections tried in each time step.
`type_dist':
Vector giving the distribution of vertex types.
`pref_matrix':
Matrix giving the connection probabilities for different vertex
types.
`directed':
Logical, whether to generate a directed graph.
*Returns:. *
`'
Error code.
Added in version 0.2.
Time complexity: O(|V|*k*log(|V|)), |V| is the number of vertices
and k is the `k' parameter.
File: igraph_reference_manual.info, Node: igraph_preference_game --- Generates a graph with vertex types and connection preferences, Next: igraph_asymmetric_preference_game --- Generates a graph with asymmetric vertex types and connection preferences, Prev: igraph_establishment_game --- Generates a graph with a simple growing model with vertex types_, Up: Games; Randomized Graph Generators
9.2.15 igraph_preference_game -- Generates a graph with vertex types and connection preferences
-----------------------------------------------------------------------------------------------
int igraph_preference_game(igraph_t *graph, igraph_integer_t nodes,
igraph_integer_t types,
const igraph_vector_t *type_dist,
igraph_bool_t fixed_sizes,
const igraph_matrix_t *pref_matrix,
igraph_vector_t *node_type_vec,
igraph_bool_t directed,
igraph_bool_t loops);
This is practically the nongrowing variant of
`igraph_establishment_game' (*note igraph_establishment_game ---
Generates a graph with a simple growing model with vertex types_::). A
given number of vertices are generated. Every vertex is assigned to a
vertex type according to the given type probabilities. Finally, every
vertex pair is evaluated and an edge is created between them with a
probability depending on the types of the vertices involved.
In other words, this function generates a graph according to a
block-model. Vertices are divided into groups (or blocks), and the
probability the two vertices are connected depends on their groups only.
*Arguments:. *
`graph':
Pointer to an uninitialized graph.
`nodes':
The number of vertices in the graph.
`types':
The number of vertex types.
`type_dist':
Vector giving the distribution of vertex types. If `NULL', all
vertex types will have equal probability. See also the
`fixed_sizes' argument.
`fixed_sizes':
Boolean. If true, then the number of vertices with a given vertex
type is fixed and the `type_dist' argument gives these numbers for
each vertex type. If true, and `type_dist' is `NULL', then the
function tries to make vertex groups of the same size. If this is
not possible, then some groups will have an extra vertex.
`pref_matrix':
Matrix giving the connection probabilities for different vertex
types. This should be symmetric if the requested graph is
undirected.
`node_type_vec':
A vector where the individual generated vertex types will be
stored. If `NULL' , the vertex types won't be saved.
`directed':
Logical, whether to generate a directed graph. If undirected
graphs are requested, only the lower left triangle of the
preference matrix is considered.
`loops':
Logical, whether loop edges are allowed.
*Returns:. *
`'
Error code.
Added in version 0.3.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
*See also:. *
`'
igraph_establishment_game()
* File examples/simple/igraph_preference_game.c*
File: igraph_reference_manual.info, Node: igraph_asymmetric_preference_game --- Generates a graph with asymmetric vertex types and connection preferences, Next: igraph_recent_degree_game --- Stochastic graph generator based on the number of incident edges a node has gained recently, Prev: igraph_preference_game --- Generates a graph with vertex types and connection preferences, Up: Games; Randomized Graph Generators
9.2.16 igraph_asymmetric_preference_game -- Generates a graph with asymmetric vertex types and connection preferences
---------------------------------------------------------------------------------------------------------------------
int igraph_asymmetric_preference_game(igraph_t *graph, igraph_integer_t nodes,
igraph_integer_t types,
igraph_matrix_t *type_dist_matrix,
igraph_matrix_t *pref_matrix,
igraph_vector_t *node_type_in_vec,
igraph_vector_t *node_type_out_vec,
igraph_bool_t loops);
This is the asymmetric variant of `igraph_preference_game()' (*note
igraph_preference_game --- Generates a graph with vertex types and
connection preferences::) . A given number of vertices are generated.
Every vertex is assigned to an "incoming" and an "outgoing" vertex type
according to the given joint type probabilities. Finally, every vertex
pair is evaluated and a directed edge is created between them with a
probability depending on the "outgoing" type of the source vertex and
the "incoming" type of the target vertex.
*Arguments:. *
`graph':
Pointer to an uninitialized graph.
`nodes':
The number of vertices in the graph.
`types':
The number of vertex types.
`type_dist_matrix':
Matrix giving the joint distribution of vertex types. If null,
incoming and outgoing vertex types are independent and uniformly
distributed.
`pref_matrix':
Matrix giving the connection probabilities for different vertex
types.
`node_type_in_vec':
A vector where the individual generated "incoming" vertex types
will be stored. If NULL, the vertex types won't be saved.
`node_type_out_vec':
A vector where the individual generated "outgoing" vertex types
will be stored. If NULL, the vertex types won't be saved.
`loops':
Logical, whether loop edges are allowed.
*Returns:. *
`'
Error code.
Added in version 0.3.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
*See also:. *
`'
`igraph_preference_game()' (*note igraph_preference_game ---
Generates a graph with vertex types and connection preferences::)
File: igraph_reference_manual.info, Node: igraph_recent_degree_game --- Stochastic graph generator based on the number of incident edges a node has gained recently, Next: igraph_barabasi_aging_game --- Preferential attachment with aging of vertices, Prev: igraph_asymmetric_preference_game --- Generates a graph with asymmetric vertex types and connection preferences, Up: Games; Randomized Graph Generators
9.2.17 igraph_recent_degree_game -- Stochastic graph generator based on the number of incident edges a node has gained recently
-------------------------------------------------------------------------------------------------------------------------------
int igraph_recent_degree_game(igraph_t *graph, igraph_integer_t n,
igraph_real_t power,
igraph_integer_t window,
igraph_integer_t m,
const igraph_vector_t *outseq,
igraph_bool_t outpref,
igraph_real_t zero_appeal,
igraph_bool_t directed);
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`n':
The number of vertices in the graph, this is the same as the
number of time steps.
`power':
The exponent, the probability that a node gains a new edge is
proportional to the number of edges it has gained recently (in the
last `window' time steps) to `power'.
`window':
Integer constant, the size of the time window to use to count the
number of recent edges.
`m':
Integer constant, the number of edges to add per time step if the
`outseq' parameter is a null pointer or a zero-length vector.
`outseq':
The number of edges to add in each time step. This argument is
ignored if it is a null pointer or a zero length vector, is this
case the constant `m' parameter is used.
`outpref':
Logical constant, if true the edges originated by a vertex also
count as recent incident edges. It is false in most cases.
`zero_appeal':
Constant giving the attractiveness of the vertices which haven't
gained any edge recently.
`directed':
Logical constant, whether to generate a directed graph.
*Returns:. *
`'
Error code.
Time complexity: O(|V|*log(|V|)+|E|), |V| is the number of vertices,
|E| is the number of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_barabasi_aging_game --- Preferential attachment with aging of vertices, Next: igraph_recent_degree_aging_game --- Preferential attachment based on the number of edges gained recently; with aging of vertices, Prev: igraph_recent_degree_game --- Stochastic graph generator based on the number of incident edges a node has gained recently, Up: Games; Randomized Graph Generators
9.2.18 igraph_barabasi_aging_game -- Preferential attachment with aging of vertices
-----------------------------------------------------------------------------------
int igraph_barabasi_aging_game(igraph_t *graph,
igraph_integer_t nodes,
igraph_integer_t m,
const igraph_vector_t *outseq,
igraph_bool_t outpref,
igraph_real_t pa_exp,
igraph_real_t aging_exp,
igraph_integer_t aging_bin,
igraph_real_t zero_deg_appeal,
igraph_real_t zero_age_appeal,
igraph_real_t deg_coef,
igraph_real_t age_coef,
igraph_bool_t directed);
In this game, the probability that a node gains a new edge is given
by its (in-)degree (k) and age (l). This probability has a degree
dependent component multiplied by an age dependent component. The
degree dependent part is: `deg_coef' times k to the power of `pa_exp'
plus `zero_deg_appeal'; and the age dependent part is `age_coef' times
l to the power of `aging_exp' plus `zero_age_appeal'.
The age is based on the number of vertices in the network and the
`aging_bin' argument: vertices grew one unit older after each
`aging_bin' vertices added to the network.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`nodes':
The number of vertices in the graph.
`m':
The number of edges to add in each time step. If the `outseq'
argument is not a null vector and not a zero-length vector.
`outseq':
The number of edges to add in each time step. If it is a null
pointer or a zero-length vector then it is ignored and the `m'
argument is used instead.
`outpref':
Logical constant, whether the edges initiated by a vertex
contribute to the probability to gain a new edge.
`pa_exp':
The exponent of the preferential attachment, a small positive
number usually, the value 1 yields the classic linear preferential
attachment.
`aging_exp':
The exponent of the aging, this is a negative number usually.
`aging_bin':
Integer constant, the number of vertices to add before vertices in
the network grew one unit older.
`zero_deg_appeal':
The degree dependent part of the attractiveness of the zero degree
vertices.
`zero_age_appeal':
The age dependent part of the attractiveness of the vertices of
age zero. This parameter is usually zero.
`deg_coef':
The coefficient for the degree.
`age_coef':
The coefficient for the age.
`directed':
Logical constant, whether to generate a directed graph.
*Returns:. *
`'
Error code.
Time complexity: O((|V|+|V|/aging_bin)*log(|V|)+|E|). |V| is the
number of vertices, |E| the number of edges.
File: igraph_reference_manual.info, Node: igraph_recent_degree_aging_game --- Preferential attachment based on the number of edges gained recently; with aging of vertices, Next: igraph_cited_type_game --- Simulate a citation based on vertex types_, Prev: igraph_barabasi_aging_game --- Preferential attachment with aging of vertices, Up: Games; Randomized Graph Generators
9.2.19 igraph_recent_degree_aging_game -- Preferential attachment based on the number of edges gained recently, with aging of vertices
--------------------------------------------------------------------------------------------------------------------------------------
int igraph_recent_degree_aging_game(igraph_t *graph,
igraph_integer_t nodes,
igraph_integer_t m,
const igraph_vector_t *outseq,
igraph_bool_t outpref,
igraph_real_t pa_exp,
igraph_real_t aging_exp,
igraph_integer_t aging_bin,
igraph_integer_t time_window,
igraph_real_t zero_appeal,
igraph_bool_t directed);
This game is very similar to `igraph_barabasi_aging_game()' (*note
igraph_barabasi_aging_game --- Preferential attachment with aging of
vertices::), except that instead of the total number of incident edges
the number of edges gained in the last `time_window' time steps are
counted.
The degree dependent part of the attractiveness is given by k to the
power of `pa_exp' plus `zero_appeal'; the age dependent part is l to
the power to `aging_exp'. k is the number of edges gained in the last
`time_window' time steps, l is the age of the vertex.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`nodes':
The number of vertices in the graph.
`m':
The number of edges to add in each time step. If the `outseq'
argument is not a null vector or a zero-length vector then it is
ignored.
`outseq':
Vector giving the number of edges to add in each time step. If it
is a null pointer or a zero-length vector then it is ignored and
the `m' argument is used.
`outpref':
Logical constant, if true the edges initiated by a vertex are also
counted. Normally it is false.
`pa_exp':
The exponent for the preferential attachment.
`aging_exp':
The exponent for the aging, normally it is negative: old vertices
gain edges with less probability.
`aging_bin':
Integer constant, gives the scale of the aging. The age of the
vertices is incremented by one after every `aging_bin' vertex
added.
`time_window':
The time window to use to count the number of incident edges for
the vertices.
`zero_appeal':
The degree dependent part of the attractiveness for zero degree
vertices.
`directed':
Logical constant, whether to create a directed graph.
*Returns:. *
`'
Error code.
Time complexity: O((|V|+|V|/aging_bin)*log(|V|)+|E|). |V| is the
number of vertices, |E| the number of edges.
File: igraph_reference_manual.info, Node: igraph_cited_type_game --- Simulate a citation based on vertex types_, Next: igraph_citing_cited_type_game --- Simulate a citation network based on vertex types_, Prev: igraph_recent_degree_aging_game --- Preferential attachment based on the number of edges gained recently; with aging of vertices, Up: Games; Randomized Graph Generators
9.2.20 igraph_cited_type_game -- Simulate a citation based on vertex types.
---------------------------------------------------------------------------
int igraph_cited_type_game(igraph_t *graph, igraph_integer_t nodes,
const igraph_vector_t *types,
const igraph_vector_t *pref,
igraph_integer_t edges_per_step,
igraph_bool_t directed);
Function to create a network based on some vertex categories. This
function creates a citation network, in each step a single vertex and
`edges_per_step' citating edges are added, nodes with different
categories (may) have different probabilities to get cited, as given by
the `pref' vector.
Note that this function might generate networks with multiple edges
if `edges_per_step' is greater than one. You might want to call
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::) on the result to remove multiple
edges.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`nodes':
The number of vertices in the network.
`types':
Numeric vector giving the categories of the vertices, so it should
contain `nodes' non-negative integer numbers. Types are numbered
from zero.
`pref':
The attractivity of the different vertex categories in a vector.
Its length should be the maximum element in `types' plus one
(types are numbered from zero).
`edges_per_step':
Integer constant, the number of edges to add in each time step.
`directed':
Logical constant, whether to create a directed network.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_citing_cited_type_game()' (*note
igraph_citing_cited_type_game --- Simulate a citation network
based on vertex types_::) for a bit more general game.
Time complexity: O((|V|+|E|)log|V|), |V| and |E| are number of
vertices and edges, respectively.
File: igraph_reference_manual.info, Node: igraph_citing_cited_type_game --- Simulate a citation network based on vertex types_, Next: igraph_sbm_game --- Sample from a stochastic block model, Prev: igraph_cited_type_game --- Simulate a citation based on vertex types_, Up: Games; Randomized Graph Generators
9.2.21 igraph_citing_cited_type_game -- Simulate a citation network based on vertex types.
------------------------------------------------------------------------------------------
int igraph_citing_cited_type_game(igraph_t *graph, igraph_integer_t nodes,
const igraph_vector_t *types,
const igraph_matrix_t *pref,
igraph_integer_t edges_per_step,
igraph_bool_t directed);
This game is similar to `igraph_cited_type_game()' (*note
igraph_cited_type_game --- Simulate a citation based on vertex
types_::) but here the category of the citing vertex is also considered.
An evolving citation network is modeled here, a single vertex and
its `edges_per_step' citation are added in each time step. The odds the
a given vertex is cited by the new vertex depends on the category of
both the citing and the cited vertex and is given in the `pref' matrix.
The categories of the citing vertex correspond to the rows, the
categories of the cited vertex to the columns of this matrix. Ie. the
element in row `i' and column `j' gives the probability that a `j'
vertex is cited, if the category of the citing vertex is `i'.
Note that this function might generate networks with multiple edges
if `edges_per_step' is greater than one. You might want to call
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::) on the result to remove multiple
edges.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`nodes':
The number of vertices in the network.
`types':
A numeric matrix of length `nodes', containing the categories of
the vertices. The categories are numbered from zero.
`pref':
The preference matrix, a square matrix is required, both the
number of rows and columns should be the maximum element in
`types' plus one (types are numbered from zero).
`directed':
Logical constant, whether to create a directed network.
*Returns:. *
`'
Error code.
Time complexity: O((|V|+|E|)log|V|), |V| and |E| are number of
vertices and edges, respectively.
File: igraph_reference_manual.info, Node: igraph_sbm_game --- Sample from a stochastic block model, Prev: igraph_citing_cited_type_game --- Simulate a citation network based on vertex types_, Up: Games; Randomized Graph Generators
9.2.22 igraph_sbm_game -- Sample from a stochastic block model
--------------------------------------------------------------
int igraph_sbm_game(igraph_t *graph, igraph_integer_t n,
const igraph_matrix_t *pref_matrix,
const igraph_vector_int_t *block_sizes,
igraph_bool_t directed, igraph_bool_t loops);
This function samples graphs from a stochastic block model by (doing
the equivalent of) Bernoulli trials for each potential edge with the
probabilities given by the Bernoulli rate matrix, `pref_matrix'. See
Faust, K., & Wasserman, S. (1992a). Blockmodels: Interpretation and
evaluation. Social Networks, 14, 5--61.
The order of the vertex ids in the generated graph corresponds to
the `block_sizes' argument.
*Arguments:. *
`graph':
The output graph.
`n':
Number of vertices.
`pref_matrix':
The matrix giving the Bernoulli rates. This is a KxK matrix,
where K is the number of groups. The probability of creating an
edge between vertices from groups i and j is given by element
(i,j).
`block_sizes':
An integer vector giving the number of vertices in each group.
`directed':
Boolean, whether to create a directed graph. If this argument is
false, then `pref_matrix' must be symmetric.
`loops':
Boolean, whether to create self-loops.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|+K^2), where |V| is the number of
vertices, |E| is the number of edges, and K is the number of groups.
*See also:. *
`'
`igraph_erdos_renyi_game()' (*note igraph_erdos_renyi_game ---
Generates a random [Erdos-Renyi] graph_::) for a simple Bernoulli
graph.
File: igraph_reference_manual.info, Node: Games on Graphs, Next: Vertex and Edge Selectors and Sequences; Iterators, Prev: Graph Generators, Up: Top
10 Games on Graphs
******************
* Menu:
* Microscopic Update Rules::
File: igraph_reference_manual.info, Node: Microscopic Update Rules, Up: Games on Graphs
10.1 Microscopic Update Rules
=============================
* Menu:
* igraph_deterministic_optimal_imitation --- Adopt a strategy via deterministic optimal imitation.: igraph_deterministic_optimal_imitation --- Adopt a strategy via deterministic optimal imitation_.
* igraph_moran_process --- The Moran process in a network setting.: igraph_moran_process --- The Moran process in a network setting_.
* igraph_roulette_wheel_imitation --- Adopt a strategy via roulette wheel selection.: igraph_roulette_wheel_imitation --- Adopt a strategy via roulette wheel selection_.
* igraph_stochastic_imitation --- Adopt a strategy via stochastic imitation with uniform selection.: igraph_stochastic_imitation --- Adopt a strategy via stochastic imitation with uniform selection_.
File: igraph_reference_manual.info, Node: igraph_deterministic_optimal_imitation --- Adopt a strategy via deterministic optimal imitation_, Next: igraph_moran_process --- The Moran process in a network setting_, Up: Microscopic Update Rules
10.1.1 igraph_deterministic_optimal_imitation -- Adopt a strategy via deterministic optimal imitation.
------------------------------------------------------------------------------------------------------
int igraph_deterministic_optimal_imitation(const igraph_t *graph,
igraph_integer_t vid,
igraph_optimal_t optimality,
const igraph_vector_t *quantities,
igraph_vector_t *strategies,
igraph_neimode_t mode);
A simple deterministic imitation strategy where a vertex revises its
strategy to that which yields a local optimal. Here "local" is with
respect to the immediate neighbours of the vertex. The vertex retains
its current strategy where this strategy yields a locally optimal
quantity. The quantity in this case could be a measure such as fitness.
*Arguments:. *
`graph':
The graph object representing the game network. This cannot be the
empty or trivial graph, but must have at least two vertices and
one edge. If `graph' has one vertex, then no strategy update would
take place. Furthermore, if `graph' has at least two vertices but
zero edges, then strategy update would also not take place.
`vid':
The vertex whose strategy is to be updated. It is assumed that
`vid' represents a vertex in `graph'. No checking is performed and
it is your responsibility to ensure that `vid' is indeed a vertex
of `graph'. If an isolated vertex is provided, i.e. the input
vertex has degree 0, then no strategy update would take place and
`vid' would retain its current strategy. Strategy update would also
not take place if the local neighbourhood of `vid' are its
in-neighbours (respectively out-neighbours), but `vid' has zero
in-neighbours (respectively out-neighbours). Loops are ignored in
computing the degree (in, out, all) of `vid'.
`optimality':
Logical; controls the type of optimality to be used. Supported
values are:
`IGRAPH_MAXIMUM'
Use maximum deterministic imitation, where the strategy of the
vertex with maximum quantity (e.g. fitness) would be adopted.
We update the strategy of `vid' to that which yields a local
maximum.
`IGRAPH_MINIMUM'
Use minimum deterministic imitation. That is, the strategy of
the vertex with minimum quantity would be imitated. In other
words, update to the strategy that yields a local minimum.
`quantities':
A vector of quantities providing the quantity of each vertex in
`graph'. Think of each entry of the vector as being generated by a
function such as the fitness function for the game. So if the
vector represents fitness quantities, then each vector entry is
the fitness of some vertex. The length of this vector must be the
same as the number of vertices in the vertex set of `graph'.
`strategies':
A vector of the current strategies for the vertex population. The
updated strategy for `vid' would be stored here. Each strategy is
identified with a nonnegative integer, whose interpretation
depends on the payoff matrix of the game. Generally we use the
strategy ID as a row or column index of the payoff matrix. The
length of this vector must be the same as the number of vertices
in the vertex set of `graph'.
`mode':
Defines the sort of neighbourhood to consider for `vid'. If
`graph' is undirected, then we use all the immediate neighbours of
`vid'. Thus if you know that `graph' is undirected, then it is safe
to pass the value `IGRAPH_ALL' here. Supported values are:
`IGRAPH_OUT'
Use the out-neighbours of `vid'. This option is only relevant
when `graph' is a directed graph.
`IGRAPH_IN'
Use the in-neighbours of `vid'. Again this option is only
relevant when `graph' is a directed graph.
`IGRAPH_ALL'
Use both the in- and out-neighbours of `vid'. This option is
only relevant if `graph' is a digraph. Also use this value if
`graph' is undirected.
*Returns:. *
`'
The error code `IGRAPH_EINVAL' is returned in each of the
following cases: (1) Any of the parameters `graph', `quantities',
or `strategies' is a null pointer. (2) The vector `quantities' or
`strategies' has a length different from the number of vertices in
`graph'. (3) The parameter `graph' is the empty or null graph,
i.e. the graph with zero vertices and edges.
Time complexity: O(2d), where d is the degree of the vertex `vid'.
* File examples/simple/igraph_deterministic_optimal_imitation.c*
File: igraph_reference_manual.info, Node: igraph_moran_process --- The Moran process in a network setting_, Next: igraph_roulette_wheel_imitation --- Adopt a strategy via roulette wheel selection_, Prev: igraph_deterministic_optimal_imitation --- Adopt a strategy via deterministic optimal imitation_, Up: Microscopic Update Rules
10.1.2 igraph_moran_process -- The Moran process in a network setting.
----------------------------------------------------------------------
int igraph_moran_process(const igraph_t *graph,
const igraph_vector_t *weights,
igraph_vector_t *quantities,
igraph_vector_t *strategies,
igraph_neimode_t mode);
This is an extension of the classic Moran process to a network
setting. The Moran process is a model of haploid (asexual)
reproduction within a population having a fixed size. In the network
setting, the Moran process operates on a weighted graph. At each time
step a vertex a is chosen for reproduction and another vertex b is
chosen for death. Vertex a gives birth to an identical clone c, which
replaces b. Vertex c is a clone of a in that c inherits both the
current quantity (e.g. fitness) and current strategy of a.
The graph G representing the game network is assumed to be simple,
i.e. free of loops and without multiple edges. If, on the other hand, G
has a loop incident on some vertex v, then it is possible that when v
is chosen for reproduction it would forgo this opportunity. In
particular, when v is chosen for reproduction and v is also chosen for
death, the clone of v would be v itself with its current vertex ID. In
effect v forgoes its chance for reproduction.
*Arguments:. *
`graph':
The graph object representing the game network. This cannot be the
empty or trivial graph, but must have at least two vertices and
one edge. The Moran process will not take place in each of the
following cases: (1) If `graph' has one vertex. (2) If `graph' has
at least two vertices but zero edges.
`weights':
A vector of all edge weights for `graph'. Thus weights[i] means
the weight of the edge with edge ID i. For the purpose of the
Moran process, each weight is assumed to be positive; it is your
responsibility to ensure this condition holds. The length of this
vector must be the same as the number of edges in `graph'.
`quantities':
A vector of quantities providing the quantity of each vertex in
`graph'. The quantity of the new clone will be stored here. Think
of each entry of the vector as being generated by a function such
as the fitness function for the game. So if the vector represents
fitness quantities, then each vector entry is the fitness of some
vertex. The length of this vector must be the same as the number
of vertices in the vertex set of `graph'. For the purpose of the
Moran process, each vector entry is assumed to be nonnegative; no
checks will be performed for this. It is your responsibility to
ensure that at least one entry is positive. Furthermore, this
vector cannot be a vector of zeros; this condition will be checked.
`strategies':
A vector of the current strategies for the vertex population. The
strategy of the new clone will be stored here. Each strategy is
identified with a nonnegative integer, whose interpretation
depends on the payoff matrix of the game. Generally we use the
strategy ID as a row or column index of the payoff matrix. The
length of this vector must be the same as the number of vertices
in the vertex set of `graph'.
`mode':
Defines the sort of neighbourhood to consider for the vertex a
chosen for reproduction. This is only relevant if `graph' is
directed. If `graph' is undirected, then it is safe to pass the
value `IGRAPH_ALL' here. Supported values are:
`IGRAPH_OUT'
Use the out-neighbours of a. This option is only relevant when
`graph' is directed.
`IGRAPH_IN'
Use the in-neighbours of a. Again this option is only relevant
when `graph' is directed.
`IGRAPH_ALL'
Use both the in- and out-neighbours of a. This option is only
relevant if `graph' is directed. Also use this value if
`graph' is undirected.
*Returns:. *
`'
The error code `IGRAPH_EINVAL' is returned in each of the following
cases: (1) Any of the parameters `graph', `weights', `quantities'
or `strategies' is a null pointer. (2) The vector `quantities' or
`strategies' has a length different from the number of vertices in
`graph'. (3) The vector `weights' has a length different from the
number of edges in `graph'. (4) The parameter `graph' is the empty
or null graph, i.e. the graph with zero vertices and edges. (5)
The vector `weights', or the combination of interest, sums to
zero. (6) The vector `quantities', or the combination of interest,
sums to zero.
Time complexity: depends on the random number generator, but is
usually O(n) where n is the number of vertices in `graph'.
References:
`(Lieberman et al. 2005)'
E. Lieberman, C. Hauert, and M. A. Nowak. Evolutionary dynamics on
graphs. _ Nature, _ 433(7023):312-316, 2005.
`(Moran 1958)'
P. A. P. Moran. Random processes in genetics. _ Mathematical
Proceedings of the Cambridge Philosophical Society, _ 54(1):60-71,
1958.
* File examples/simple/igraph_moran_process.c*
File: igraph_reference_manual.info, Node: igraph_roulette_wheel_imitation --- Adopt a strategy via roulette wheel selection_, Next: igraph_stochastic_imitation --- Adopt a strategy via stochastic imitation with uniform selection_, Prev: igraph_moran_process --- The Moran process in a network setting_, Up: Microscopic Update Rules
10.1.3 igraph_roulette_wheel_imitation -- Adopt a strategy via roulette wheel selection.
----------------------------------------------------------------------------------------
int igraph_roulette_wheel_imitation(const igraph_t *graph,
igraph_integer_t vid,
igraph_bool_t islocal,
const igraph_vector_t *quantities,
igraph_vector_t *strategies,
igraph_neimode_t mode);
A simple stochastic imitation strategy where a vertex revises its
strategy to that of a vertex u chosen proportionate to u's quantity
(e.g. fitness). This is a special case of stochastic imitation, where a
candidate is not chosen uniformly at random but proportionate to its
quantity.
*Arguments:. *
`graph':
The graph object representing the game network. This cannot be the
empty or trivial graph, but must have at least two vertices and
one edge. If `graph' has one vertex, then no strategy update would
take place. Furthermore, if `graph' has at least two vertices but
zero edges, then strategy update would also not take place.
`vid':
The vertex whose strategy is to be updated. It is assumed that
`vid' represents a vertex in `graph'. No checking is performed and
it is your responsibility to ensure that `vid' is indeed a vertex
of `graph'. If an isolated vertex is provided, i.e. the input
vertex has degree 0, then no strategy update would take place and
`vid' would retain its current strategy. Strategy update would also
not take place if the local neighbourhood of `vid' are its
in-neighbours (respectively out-neighbours), but `vid' has zero
in-neighbours (respectively out-neighbours). Loops are ignored in
computing the degree (in, out, all) of `vid'.
`islocal':
Boolean; this flag controls which perspective to use in computing
the relative quantity. If true then we use the local perspective;
otherwise we use the global perspective. The local perspective for
`vid' is the set of all immediate neighbours of `vid'. In
contrast, the global perspective for `vid' is the vertex set of
`graph'.
`quantities':
A vector of quantities providing the quantity of each vertex in
`graph'. Think of each entry of the vector as being generated by a
function such as the fitness function for the game. So if the
vector represents fitness quantities, then each vector entry is
the fitness of some vertex. The length of this vector must be the
same as the number of vertices in the vertex set of `graph'. For
the purpose of roulette wheel selection, each vector entry is
assumed to be nonnegative; no checks will be performed for this. It
is your responsibility to ensure that at least one entry is
nonzero. Furthermore, this vector cannot be a vector of zeros;
this condition will be checked.
`strategies':
A vector of the current strategies for the vertex population. The
updated strategy for `vid' would be stored here. Each strategy is
identified with a nonnegative integer, whose interpretation
depends on the payoff matrix of the game. Generally we use the
strategy ID as a row or column index of the payoff matrix. The
length of this vector must be the same as the number of vertices
in the vertex set of `graph'.
`mode':
Defines the sort of neighbourhood to consider for `vid'. This is
only relevant if we are considering the local perspective, i.e. if
`islocal' is true. If we are considering the global perspective,
then it is safe to pass the value `IGRAPH_ALL' here. If `graph' is
undirected, then we use all the immediate neighbours of `vid'. Thus
if you know that `graph' is undirected, then it is safe to pass the
value `IGRAPH_ALL' here. Supported values are:
`IGRAPH_OUT'
Use the out-neighbours of `vid'. This option is only relevant
when `graph' is a digraph and we are considering the local
perspective.
`IGRAPH_IN'
Use the in-neighbours of `vid'. Again this option is only
relevant when `graph' is a directed graph and we are
considering the local perspective.
`IGRAPH_ALL'
Use both the in- and out-neighbours of `vid'. This option is
only relevant if `graph' is a digraph. Also use this value if
`graph' is undirected or we are considering the global
perspective.
*Returns:. *
`'
The error code `IGRAPH_EINVAL' is returned in each of the following
cases: (1) Any of the parameters `graph', `quantities', or
`strategies' is a null pointer. (2) The vector `quantities' or
`strategies' has a length different from the number of vertices in
`graph'. (3) The parameter `graph' is the empty or null graph,
i.e. the graph with zero vertices and edges. (4) The vector
`quantities' sums to zero.
Time complexity: O(n) where n is the number of vertices in the
perspective to consider. If we consider the global perspective, then n
is the number of vertices in the vertex set of `graph'. On the other
hand, for the local perspective n is the degree of `vid', excluding
loops.
Reference:
`(Yu & Gen 2010)'
X. Yu and M. Gen. _ Introduction to Evolutionary Algorithms. _
Springer, 2010, pages 18-20.
* File examples/simple/igraph_roulette_wheel_imitation.c*
File: igraph_reference_manual.info, Node: igraph_stochastic_imitation --- Adopt a strategy via stochastic imitation with uniform selection_, Prev: igraph_roulette_wheel_imitation --- Adopt a strategy via roulette wheel selection_, Up: Microscopic Update Rules
10.1.4 igraph_stochastic_imitation -- Adopt a strategy via stochastic imitation with uniform selection.
-------------------------------------------------------------------------------------------------------
int igraph_stochastic_imitation(const igraph_t *graph,
igraph_integer_t vid,
igraph_imitate_algorithm_t algo,
const igraph_vector_t *quantities,
igraph_vector_t *strategies,
igraph_neimode_t mode);
A simple stochastic imitation strategy where a vertex revises its
strategy to that of a vertex chosen uniformly at random from its local
neighbourhood. This is called stochastic imitation via uniform
selection, where the strategy to imitate is chosen via some random
process. For the purposes of this function, we use uniform selection
from a pool of candidates.
*Arguments:. *
`graph':
The graph object representing the game network. This cannot be the
empty or trivial graph, but must have at least two vertices and
one edge. If `graph' has one vertex, then no strategy update would
take place. Furthermore, if `graph' has at least two vertices but
zero edges, then strategy update would also not take place.
`vid':
The vertex whose strategy is to be updated. It is assumed that
`vid' represents a vertex in `graph'. No checking is performed and
it is your responsibility to ensure that `vid' is indeed a vertex
of `graph'. If an isolated vertex is provided, i.e. the input
vertex has degree 0, then no strategy update would take place and
`vid' would retain its current strategy. Strategy update would also
not take place if the local neighbourhood of `vid' are its
in-neighbours (respectively out-neighbours), but `vid' has zero
in-neighbours (respectively out-neighbours). Loops are ignored in
computing the degree (in, out, all) of `vid'.
`algo':
This flag controls which algorithm to use in stochastic imitation.
Supported values are:
`IGRAPH_IMITATE_AUGMENTED'
Augmented imitation. Vertex `vid' imitates the strategy of the
chosen vertex u provided that doing so would increase the
quantity (e.g. fitness) of `vid'. Augmented imitation can be
thought of as "imitate if better".
`IGRAPH_IMITATE_BLIND'
Blind imitation. Vertex `vid' blindly imitates the strategy of
the chosen vertex u, regardless of whether doing so would
increase or decrease the quantity of `vid'.
`IGRAPH_IMITATE_CONTRACTED'
Contracted imitation. Here vertex `vid' imitates the strategy
of the chosen vertex u if doing so would decrease the
quantity of `vid'. Think of contracted imitation as "imitate
if worse".
`quantities':
A vector of quantities providing the quantity of each vertex in
`graph'. Think of each entry of the vector as being generated by a
function such as the fitness function for the game. So if the
vector represents fitness quantities, then each vector entry is
the fitness of some vertex. The length of this vector must be the
same as the number of vertices in the vertex set of `graph'.
`strategies':
A vector of the current strategies for the vertex population. The
updated strategy for `vid' would be stored here. Each strategy is
identified with a nonnegative integer, whose interpretation
depends on the payoff matrix of the game. Generally we use the
strategy ID as a row or column index of the payoff matrix. The
length of this vector must be the same as the number of vertices
in the vertex set of `graph'.
`mode':
Defines the sort of neighbourhood to consider for `vid'. If
`graph' is undirected, then we use all the immediate neighbours of
`vid'. Thus if you know that `graph' is undirected, then it is safe
to pass the value `IGRAPH_ALL' here. Supported values are:
`IGRAPH_OUT'
Use the out-neighbours of `vid'. This option is only relevant
when `graph' is a directed graph.
`IGRAPH_IN'
Use the in-neighbours of `vid'. Again this option is only
relevant when `graph' is a directed graph.
`IGRAPH_ALL'
Use both the in- and out-neighbours of `vid'. This option is
only relevant if `graph' is a digraph. Also use this value if
`graph' is undirected.
*Returns:. *
`'
The error code `IGRAPH_EINVAL' is returned in each of the following
cases: (1) Any of the parameters `graph', `quantities', or
`strategies' is a null pointer. (2) The vector `quantities' or
`strategies' has a length different from the number of vertices in
`graph'. (3) The parameter `graph' is the empty or null graph,
i.e. the graph with zero vertices and edges. (4) The parameter
`algo' refers to an unsupported stochastic imitation algorithm.
Time complexity: depends on the uniform random number generator, but
should usually be O(1).
* File examples/simple/igraph_stochastic_imitation.c*
File: igraph_reference_manual.info, Node: Vertex and Edge Selectors and Sequences; Iterators, Next: Graph; Vertex and Edge Attributes, Prev: Games on Graphs, Up: Top
11 Vertex and Edge Selectors and Sequences, Iterators
*****************************************************
* Menu:
* About selectors, iterators: About selectors; iterators.
* Vertex selector constructors::
* Generic vertex selector operations::
* Immediate vertex selectors::
* Vertex iterators::
* Edge selector constructors::
* Immediate edge selectors::
* Generic edge selector operations::
* Edge iterators::
File: igraph_reference_manual.info, Node: About selectors; iterators, Next: Vertex selector constructors, Up: Vertex and Edge Selectors and Sequences; Iterators
11.1 About selectors, iterators
===============================
Everything about vertices and vertex selectors also applies to edges
and edge selectors unless explicitly noted otherwise.
The vertex (and edge) selector notion was introduced in igraph 0.2.
It is a way to reference a sequence of vertices or edges independently
of the graph.
While this might sound quite mysterious, it is actually very simple.
For example, all vertices of a graph can be selected by
`igraph_vs_all()' (*note igraph_vs_all --- Vertex set; all vertices of
a graph_::) and the graph independence means that `igraph_vs_all()'
(*note igraph_vs_all --- Vertex set; all vertices of a graph_::) is not
parametrized by a graph object. That is, `igraph_vs_all()' (*note
igraph_vs_all --- Vertex set; all vertices of a graph_::) is the
general _concept_ of selecting all vertices of a graph. A vertex
selector is then a way to specify the class of vertices to be visited.
The selector might specify that all vertices of a graph or all the
neighbours of a vertex are to be visited. A vertex selector is a way of
saying that you want to visit a bunch of vertices, as opposed to a
vertex iterator which is a concrete plan for visiting each of the
chosen vertices of a specific graph.
To determine the actual vertex IDs implied by a vertex selector, you
need to apply the concept of selecting vertices to a specific graph
object. This can be accomplished by instantiating a vertex iterator
using a specific vertex selection concept and a specific graph object.
The notion of vertex iterators can be thought of in the following way.
Given a specific graph object and the class of vertices to be visited,
a vertex iterator is a road map, plan or route for how to visit the
chosen vertices.
Some vertex selectors have _immediate_ versions. These have the
prefix `igraph_vss' instead of `igraph_vs', e.g. `igraph_vss_all()'
(*note igraph_vss_all --- All vertices of a graph [immediate
version]_::) instead of `igraph_vs_all()' (*note igraph_vs_all ---
Vertex set; all vertices of a graph_::). The immediate versions are to
be used in the parameter list of the igraph functions, such as
`igraph_degree()' (*note igraph_degree --- The degree of some vertices
in a graph_::). These functions are not associated with any
`igraph_vs_t' object, so they have no separate constructors and
destructors (destroy functions).
File: igraph_reference_manual.info, Node: Vertex selector constructors, Next: Generic vertex selector operations, Prev: About selectors; iterators, Up: Vertex and Edge Selectors and Sequences; Iterators
11.2 Vertex selector constructors
=================================
Vertex selectors are created by vertex selector constructors, can be
instantiated with `igraph_vit_create()' (*note igraph_vit_create ---
Creates a vertex iterator from a vertex selector_::), and are destroyed
with `igraph_vs_destroy()' (*note igraph_vs_destroy --- Destroy a
vertex set_::).
* Menu:
* igraph_vs_all --- Vertex set, all vertices of a graph.: igraph_vs_all --- Vertex set; all vertices of a graph_.
* igraph_vs_adj --- Adjacent vertices of a vertex.: igraph_vs_adj --- Adjacent vertices of a vertex_.
* igraph_vs_nonadj --- Non-adjacent vertices of a vertex.: igraph_vs_nonadj --- Non-adjacent vertices of a vertex_.
* igraph_vs_none --- Empty vertex set.: igraph_vs_none --- Empty vertex set_.
* igraph_vs_1 --- Vertex set with a single vertex.: igraph_vs_1 --- Vertex set with a single vertex_.
* igraph_vs_vector --- Vertex set based on a vector.: igraph_vs_vector --- Vertex set based on a vector_.
* igraph_vs_vector_small --- Create a vertex set by giving its elements.: igraph_vs_vector_small --- Create a vertex set by giving its elements_.
* igraph_vs_vector_copy --- Vertex set based on a vector, with copying.: igraph_vs_vector_copy --- Vertex set based on a vector; with copying_.
* igraph_vs_seq --- Vertex set, an interval of vertices.: igraph_vs_seq --- Vertex set; an interval of vertices_.
File: igraph_reference_manual.info, Node: igraph_vs_all --- Vertex set; all vertices of a graph_, Next: igraph_vs_adj --- Adjacent vertices of a vertex_, Up: Vertex selector constructors
11.2.1 igraph_vs_all -- Vertex set, all vertices of a graph.
------------------------------------------------------------
int igraph_vs_all(igraph_vs_t *vs);
*Arguments:. *
`vs':
Pointer to an uninitialized `igraph_vs_t' object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vss_all()' (*note igraph_vss_all --- All vertices of a
graph [immediate version]_::), `igraph_vs_destroy()' (*note
igraph_vs_destroy --- Destroy a vertex set_::)
This selector includes all vertices of a given graph in increasing
vertex id order.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_adj --- Adjacent vertices of a vertex_, Next: igraph_vs_nonadj --- Non-adjacent vertices of a vertex_, Prev: igraph_vs_all --- Vertex set; all vertices of a graph_, Up: Vertex selector constructors
11.2.2 igraph_vs_adj -- Adjacent vertices of a vertex.
------------------------------------------------------
int igraph_vs_adj(igraph_vs_t *vs,
igraph_integer_t vid, igraph_neimode_t mode);
All neighboring vertices of a given vertex are selected by this
selector. The `mode' argument controls the type of the neighboring
vertices to be selected. The vertices are visited in increasing vertex
ID order, as of igraph version 0.4.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
`vid':
Vertex ID, the center of the neighborhood.
`mode':
Decides the type of the neighborhood for directed graphs. This
parameter is ignored for undirected graphs. Possible values:
`IGRAPH_OUT'
All vertices to which there is a directed edge from `vid'.
That is, all the out-neighbors of `vid'.
`IGRAPH_IN'
All vertices from which there is a directed edge to `vid'. In
other words, all the in-neighbors of `vid'.
`IGRAPH_ALL'
All vertices to which or from which there is a directed edge
from/to `vid'. That is, all the neighbors of `vid' considered
as if the graph is undirected.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vs_destroy()' (*note igraph_vs_destroy --- Destroy a
vertex set_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_nonadj --- Non-adjacent vertices of a vertex_, Next: igraph_vs_none --- Empty vertex set_, Prev: igraph_vs_adj --- Adjacent vertices of a vertex_, Up: Vertex selector constructors
11.2.3 igraph_vs_nonadj -- Non-adjacent vertices of a vertex.
-------------------------------------------------------------
int igraph_vs_nonadj(igraph_vs_t *vs, igraph_integer_t vid,
igraph_neimode_t mode);
All non-neighboring vertices of a given vertex. The `mode' argument
controls the type of neighboring vertices _not_ to select. Instead of
selecting immediate neighbors of `vid' as is done by `igraph_vs_adj()'
(*note igraph_vs_adj --- Adjacent vertices of a vertex_::), the current
function selects vertices that are _not_ immediate neighbors of `vid'.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
`vid':
Vertex ID, the `center' of the non-neighborhood.
`mode':
The type of neighborhood not to select in directed graphs.
Possible values:
`IGRAPH_OUT'
All vertices will be selected except those to which there is a
directed edge from `vid'. That is, we select all vertices
excluding the out-neighbors of `vid'.
`IGRAPH_IN'
All vertices will be selected except those from which there
is a directed edge to `vid'. In other words, we select all
vertices but the in-neighbors of `vid'.
`IGRAPH_ALL'
All vertices will be selected except those from or to which
there is a directed edge to or from `vid'. That is, we select
all vertices of `vid' except for its immediate neighbors.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vs_destroy()' (*note igraph_vs_destroy --- Destroy a
vertex set_::)
Time complexity: O(1).
* File examples/simple/igraph_vs_nonadj.c*
File: igraph_reference_manual.info, Node: igraph_vs_none --- Empty vertex set_, Next: igraph_vs_1 --- Vertex set with a single vertex_, Prev: igraph_vs_nonadj --- Non-adjacent vertices of a vertex_, Up: Vertex selector constructors
11.2.4 igraph_vs_none -- Empty vertex set.
------------------------------------------
int igraph_vs_none(igraph_vs_t *vs);
Creates an empty vertex selector.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vss_none()' (*note igraph_vss_none --- Empty vertex set
[immediate version]_::), `igraph_vs_destroy()' (*note
igraph_vs_destroy --- Destroy a vertex set_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_1 --- Vertex set with a single vertex_, Next: igraph_vs_vector --- Vertex set based on a vector_, Prev: igraph_vs_none --- Empty vertex set_, Up: Vertex selector constructors
11.2.5 igraph_vs_1 -- Vertex set with a single vertex.
------------------------------------------------------
int igraph_vs_1(igraph_vs_t *vs, igraph_integer_t vid);
This vertex selector selects a single vertex.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
`vid':
The vertex id to be selected.
*Returns:. *
`'
Error Code.
*See also:. *
`'
`igraph_vss_1()' (*note igraph_vss_1 --- Vertex set with a single
vertex [immediate version]_::), `igraph_vs_destroy()' (*note
igraph_vs_destroy --- Destroy a vertex set_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_vector --- Vertex set based on a vector_, Next: igraph_vs_vector_small --- Create a vertex set by giving its elements_, Prev: igraph_vs_1 --- Vertex set with a single vertex_, Up: Vertex selector constructors
11.2.6 igraph_vs_vector -- Vertex set based on a vector.
--------------------------------------------------------
int igraph_vs_vector(igraph_vs_t *vs,
const igraph_vector_t *v);
This function makes it possible to handle a `vector_t' temporarily
as a vertex selector. The vertex selector should be thought of like a
_view_ to the vector. If you make changes to the vector that also
affects the vertex selector. Destroying the vertex selector does not
destroy the vector. (Of course.) Do not destroy the vector before
destroying the vertex selector, or you might get strange behavior.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector.
`v':
Pointer to a `igraph_vector_t' object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vss_vector()' (*note igraph_vss_vector --- Vertex set
based on a vector [immediate version]_::), `igraph_vs_destroy()'
(*note igraph_vs_destroy --- Destroy a vertex set_::)
Time complexity: O(1).
* File examples/simple/igraph_vs_vector.c*
File: igraph_reference_manual.info, Node: igraph_vs_vector_small --- Create a vertex set by giving its elements_, Next: igraph_vs_vector_copy --- Vertex set based on a vector; with copying_, Prev: igraph_vs_vector --- Vertex set based on a vector_, Up: Vertex selector constructors
11.2.7 igraph_vs_vector_small -- Create a vertex set by giving its elements.
----------------------------------------------------------------------------
int igraph_vs_vector_small(igraph_vs_t *vs, ...);
This function can be used to create a vertex selector with a couple
of vertices. Do not forget to include a ` -1' after the last vertex
id. The behavior of the function is undefined if you don't use a ` -1'
properly.
Note that the vertex ids supplied will be parsed as ` int' 's so you
cannot supply arbitrarily large (too large for int) vertex ids here.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
`...':
Additional parameters, these will be the vertex ids to be included
in the vertex selector. Supply a ` -1' after the last vertex id.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vs_destroy()' (*note igraph_vs_destroy --- Destroy a
vertex set_::)
Time complexity: O(n), the number of vertex ids supplied.
File: igraph_reference_manual.info, Node: igraph_vs_vector_copy --- Vertex set based on a vector; with copying_, Next: igraph_vs_seq --- Vertex set; an interval of vertices_, Prev: igraph_vs_vector_small --- Create a vertex set by giving its elements_, Up: Vertex selector constructors
11.2.8 igraph_vs_vector_copy -- Vertex set based on a vector, with copying.
---------------------------------------------------------------------------
int igraph_vs_vector_copy(igraph_vs_t *vs,
const igraph_vector_t *v);
This function makes it possible to handle a `vector_t' permanently
as a vertex selector. The vertex selector creates a copy of the
original vector, so the vector can safely be destroyed after creating
the vertex selector. Changing the original vector will not affect the
vertex selector. The vertex selector is responsible for deleting the
copy made by itself.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector.
`v':
Pointer to a `igraph_vector_t' object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vs_destroy()' (*note igraph_vs_destroy --- Destroy a
vertex set_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_seq --- Vertex set; an interval of vertices_, Prev: igraph_vs_vector_copy --- Vertex set based on a vector; with copying_, Up: Vertex selector constructors
11.2.9 igraph_vs_seq -- Vertex set, an interval of vertices.
------------------------------------------------------------
int igraph_vs_seq(igraph_vs_t *vs,
igraph_integer_t from, igraph_integer_t to);
Creates a vertex selector containing all vertices with vertex id
equal to or bigger than `from' and equal to or smaller than `to'.
*Arguments:. *
`vs':
Pointer to an uninitialized vertex selector object.
`from':
The first vertex id to be included in the vertex selector.
`to':
The last vertex id to be included in the vertex selector.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vss_seq()' (*note igraph_vss_seq --- An interval of
vertices [immediate version]_::), `igraph_vs_destroy()' (*note
igraph_vs_destroy --- Destroy a vertex set_::)
Time complexity: O(1).
* File examples/simple/igraph_vs_seq.c*
File: igraph_reference_manual.info, Node: Generic vertex selector operations, Next: Immediate vertex selectors, Prev: Vertex selector constructors, Up: Vertex and Edge Selectors and Sequences; Iterators
11.3 Generic vertex selector operations
=======================================
* Menu:
* igraph_vs_copy --- Creates a copy of a vertex selector.: igraph_vs_copy --- Creates a copy of a vertex selector_.
* igraph_vs_destroy --- Destroy a vertex set.: igraph_vs_destroy --- Destroy a vertex set_.
* igraph_vs_is_all --- Check whether all vertices are included.: igraph_vs_is_all --- Check whether all vertices are included_.
* igraph_vs_size --- Returns the size of the vertex selector.: igraph_vs_size --- Returns the size of the vertex selector_.
* igraph_vs_type --- Returns the type of the vertex selector.: igraph_vs_type --- Returns the type of the vertex selector_.
File: igraph_reference_manual.info, Node: igraph_vs_copy --- Creates a copy of a vertex selector_, Next: igraph_vs_destroy --- Destroy a vertex set_, Up: Generic vertex selector operations
11.3.1 igraph_vs_copy -- Creates a copy of a vertex selector.
-------------------------------------------------------------
int igraph_vs_copy(igraph_vs_t* dest, const igraph_vs_t* src);
*Arguments:. *
`src':
The selector being copied.
`dest':
An uninitialized selector that will contain the copy.
File: igraph_reference_manual.info, Node: igraph_vs_destroy --- Destroy a vertex set_, Next: igraph_vs_is_all --- Check whether all vertices are included_, Prev: igraph_vs_copy --- Creates a copy of a vertex selector_, Up: Generic vertex selector operations
11.3.2 igraph_vs_destroy -- Destroy a vertex set.
-------------------------------------------------
void igraph_vs_destroy(igraph_vs_t *vs);
This function should be called for all vertex selectors when they
are not needed. The memory allocated for the vertex selector will be
deallocated. Do not call this function on vertex selectors created with
the immediate versions of the vertex selector constructors (starting
with ` igraph_vss' ).
*Arguments:. *
`vs':
Pointer to a vertex selector object.
Time complexity: operating system dependent, usually O(1).
File: igraph_reference_manual.info, Node: igraph_vs_is_all --- Check whether all vertices are included_, Next: igraph_vs_size --- Returns the size of the vertex selector_, Prev: igraph_vs_destroy --- Destroy a vertex set_, Up: Generic vertex selector operations
11.3.3 igraph_vs_is_all -- Check whether all vertices are included.
-------------------------------------------------------------------
igraph_bool_t igraph_vs_is_all(const igraph_vs_t *vs);
This function checks whether the vertex selector object was created
by `igraph_vs_all()' (*note igraph_vs_all --- Vertex set; all vertices
of a graph_::) or `igraph_vss_all()' (*note igraph_vss_all --- All
vertices of a graph [immediate version]_::). Note that the vertex
selector might contain all vertices in a given graph but if it wasn't
created by the two constructors mentioned here the return value will be
FALSE.
*Arguments:. *
`vs':
Pointer to a vertex selector object.
*Returns:. *
`'
TRUE (1) if the vertex selector contains all vertices and FALSE
(0) otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vs_size --- Returns the size of the vertex selector_, Next: igraph_vs_type --- Returns the type of the vertex selector_, Prev: igraph_vs_is_all --- Check whether all vertices are included_, Up: Generic vertex selector operations
11.3.4 igraph_vs_size -- Returns the size of the vertex selector.
-----------------------------------------------------------------
int igraph_vs_size(const igraph_t *graph, const igraph_vs_t *vs,
igraph_integer_t *result);
The size of the vertex selector is the number of vertices it will
yield when it is iterated over.
*Arguments:. *
`graph':
The graph over which we will iterate.
`result':
The result will be returned here.
File: igraph_reference_manual.info, Node: igraph_vs_type --- Returns the type of the vertex selector_, Prev: igraph_vs_size --- Returns the size of the vertex selector_, Up: Generic vertex selector operations
11.3.5 igraph_vs_type -- Returns the type of the vertex selector.
-----------------------------------------------------------------
int igraph_vs_type(const igraph_vs_t *vs);
File: igraph_reference_manual.info, Node: Immediate vertex selectors, Next: Vertex iterators, Prev: Generic vertex selector operations, Up: Vertex and Edge Selectors and Sequences; Iterators
11.4 Immediate vertex selectors
===============================
* Menu:
* igraph_vss_all --- All vertices of a graph (immediate version).: igraph_vss_all --- All vertices of a graph [immediate version]_.
* igraph_vss_none --- Empty vertex set (immediate version).: igraph_vss_none --- Empty vertex set [immediate version]_.
* igraph_vss_1 --- Vertex set with a single vertex (immediate version).: igraph_vss_1 --- Vertex set with a single vertex [immediate version]_.
* igraph_vss_vector --- Vertex set based on a vector (immediate version).: igraph_vss_vector --- Vertex set based on a vector [immediate version]_.
* igraph_vss_seq --- An interval of vertices (immediate version).: igraph_vss_seq --- An interval of vertices [immediate version]_.
File: igraph_reference_manual.info, Node: igraph_vss_all --- All vertices of a graph [immediate version]_, Next: igraph_vss_none --- Empty vertex set [immediate version]_, Up: Immediate vertex selectors
11.4.1 igraph_vss_all -- All vertices of a graph (immediate version).
---------------------------------------------------------------------
igraph_vs_t igraph_vss_all(void);
Immediate vertex selector for all vertices in a graph. It can be
used conveniently when some vertex property (eg. betweenness, degree,
etc.) should be calculated for all vertices.
*Returns:. *
`'
A vertex selector for all vertices in a graph.
*See also:. *
`'
`igraph_vs_all()' (*note igraph_vs_all --- Vertex set; all
vertices of a graph_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vss_none --- Empty vertex set [immediate version]_, Next: igraph_vss_1 --- Vertex set with a single vertex [immediate version]_, Prev: igraph_vss_all --- All vertices of a graph [immediate version]_, Up: Immediate vertex selectors
11.4.2 igraph_vss_none -- Empty vertex set (immediate version).
---------------------------------------------------------------
igraph_vs_t igraph_vss_none(void);
The immediate version of the empty vertex selector.
*Returns:. *
`'
An empty vertex selector.
*See also:. *
`'
`igraph_vs_none()' (*note igraph_vs_none --- Empty vertex set_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vss_1 --- Vertex set with a single vertex [immediate version]_, Next: igraph_vss_vector --- Vertex set based on a vector [immediate version]_, Prev: igraph_vss_none --- Empty vertex set [immediate version]_, Up: Immediate vertex selectors
11.4.3 igraph_vss_1 -- Vertex set with a single vertex (immediate version).
---------------------------------------------------------------------------
igraph_vs_t igraph_vss_1(igraph_integer_t vid);
The immediate version of the single-vertex selector.
*Arguments:. *
`vid':
The vertex to be selected.
*Returns:. *
`'
A vertex selector containing a single vertex.
*See also:. *
`'
`igraph_vs_1()' (*note igraph_vs_1 --- Vertex set with a single
vertex_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vss_vector --- Vertex set based on a vector [immediate version]_, Next: igraph_vss_seq --- An interval of vertices [immediate version]_, Prev: igraph_vss_1 --- Vertex set with a single vertex [immediate version]_, Up: Immediate vertex selectors
11.4.4 igraph_vss_vector -- Vertex set based on a vector (immediate version).
-----------------------------------------------------------------------------
igraph_vs_t igraph_vss_vector(const igraph_vector_t *v);
This is the immediate version of `igraph_vs_vector' (*note
igraph_vs_vector --- Vertex set based on a vector_::).
*Arguments:. *
`v':
Pointer to a `igraph_vector_t' object.
*Returns:. *
`'
A vertex selector object containing the vertices in the vector.
*See also:. *
`'
`igraph_vs_vector()' (*note igraph_vs_vector --- Vertex set based
on a vector_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_vss_seq --- An interval of vertices [immediate version]_, Prev: igraph_vss_vector --- Vertex set based on a vector [immediate version]_, Up: Immediate vertex selectors
11.4.5 igraph_vss_seq -- An interval of vertices (immediate version).
---------------------------------------------------------------------
igraph_vs_t igraph_vss_seq(igraph_integer_t from, igraph_integer_t to);
The immediate version of `igraph_vs_seq()' (*note igraph_vs_seq ---
Vertex set; an interval of vertices_::).
*Arguments:. *
`from':
The first vertex id to be included in the vertex selector.
`to':
The last vertex id to be included in the vertex selector.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vs_seq()' (*note igraph_vs_seq --- Vertex set; an interval
of vertices_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Vertex iterators, Next: Edge selector constructors, Prev: Immediate vertex selectors, Up: Vertex and Edge Selectors and Sequences; Iterators
11.5 Vertex iterators
=====================
* Menu:
* igraph_vit_create --- Creates a vertex iterator from a vertex selector.: igraph_vit_create --- Creates a vertex iterator from a vertex selector_.
* igraph_vit_destroy --- Destroys a vertex iterator.: igraph_vit_destroy --- Destroys a vertex iterator_.
* Stepping over the vertices::
* IGRAPH_VIT_NEXT --- Next vertex.: IGRAPH_VIT_NEXT --- Next vertex_.
* IGRAPH_VIT_END --- Are we at the end?::
* IGRAPH_VIT_SIZE --- Size of a vertex iterator.: IGRAPH_VIT_SIZE --- Size of a vertex iterator_.
* IGRAPH_VIT_RESET --- Reset a vertex iterator.: IGRAPH_VIT_RESET --- Reset a vertex iterator_.
* IGRAPH_VIT_GET --- Query the current position.: IGRAPH_VIT_GET --- Query the current position_.
File: igraph_reference_manual.info, Node: igraph_vit_create --- Creates a vertex iterator from a vertex selector_, Next: igraph_vit_destroy --- Destroys a vertex iterator_, Up: Vertex iterators
11.5.1 igraph_vit_create -- Creates a vertex iterator from a vertex selector.
-----------------------------------------------------------------------------
int igraph_vit_create(const igraph_t *graph,
igraph_vs_t vs, igraph_vit_t *vit);
This function instantiates a vertex selector object with a given
graph. This is the step when the actual vertex ids are created from the
_logical_ notion of the vertex selector based on the graph. Eg. a
vertex selector created with `igraph_vs_all()' (*note igraph_vs_all ---
Vertex set; all vertices of a graph_::) contains knowledge that _all_
vertices are included in a (yet indefinite) graph. When instantiating
it a vertex iterator object is created, this contains the actual vertex
ids in the graph supplied as a parameter.
The same vertex selector object can be used to instantiate any
number vertex iterators.
*Arguments:. *
`graph':
An `igraph_t' object, a graph.
`vs':
A vertex selector object.
`vit':
Pointer to an uninitialized vertex iterator object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_vit_destroy()' (*note igraph_vit_destroy --- Destroys a
vertex iterator_::).
Time complexity: it depends on the vertex selector type. O(1) for
vertex selectors created with `igraph_vs_all()' (*note igraph_vs_all
--- Vertex set; all vertices of a graph_::), `igraph_vs_none()' (*note
igraph_vs_none --- Empty vertex set_::), `igraph_vs_1' (*note
igraph_vs_1 --- Vertex set with a single vertex_::), `igraph_vs_vector'
(*note igraph_vs_vector --- Vertex set based on a vector_::),
`igraph_vs_seq()' (*note igraph_vs_seq --- Vertex set; an interval of
vertices_::), `igraph_vs_vector()' (*note igraph_vs_vector --- Vertex
set based on a vector_::), `igraph_vs_vector_small()' (*note
igraph_vs_vector_small --- Create a vertex set by giving its
elements_::). O(d) for `igraph_vs_adj()' (*note igraph_vs_adj ---
Adjacent vertices of a vertex_::), d is the number of vertex ids to be
included in the iterator. O(|V|) for `igraph_vs_nonadj()' (*note
igraph_vs_nonadj --- Non-adjacent vertices of a vertex_::), |V| is the
number of vertices in the graph.
File: igraph_reference_manual.info, Node: igraph_vit_destroy --- Destroys a vertex iterator_, Next: Stepping over the vertices, Prev: igraph_vit_create --- Creates a vertex iterator from a vertex selector_, Up: Vertex iterators
11.5.2 igraph_vit_destroy -- Destroys a vertex iterator.
--------------------------------------------------------
void igraph_vit_destroy(const igraph_vit_t *vit);
Deallocates memory allocated for a vertex iterator.
*Arguments:. *
`vit':
Pointer to an initialized vertex iterator object.
*See also:. *
`'
`igraph_vit_create()' (*note igraph_vit_create --- Creates a
vertex iterator from a vertex selector_::)
Time complexity: operating system dependent, usually O(1).
File: igraph_reference_manual.info, Node: Stepping over the vertices, Next: IGRAPH_VIT_NEXT --- Next vertex_, Prev: igraph_vit_destroy --- Destroys a vertex iterator_, Up: Vertex iterators
11.5.3 Stepping over the vertices
---------------------------------
After creating an iterator with `igraph_vit_create()' (*note
igraph_vit_create --- Creates a vertex iterator from a vertex
selector_::), it points to the first vertex in the vertex determined by
the vertex selector (if there is any). The `IGRAPH_VIT_NEXT()' (*note
IGRAPH_VIT_NEXT --- Next vertex_::) macro steps to the next vertex,
`IGRAPH_VIT_END()' (*note IGRAPH_VIT_END --- Are we at the end?::)
checks whether there are more vertices to visit, `IGRAPH_VIT_SIZE()'
(*note IGRAPH_VIT_SIZE --- Size of a vertex iterator_::) gives the
total size of the vertices visited so far and to be visited.
`IGRAPH_VIT_RESET()' (*note IGRAPH_VIT_RESET --- Reset a vertex
iterator_::) resets the iterator, it will point to the first vertex
again. Finally `IGRAPH_VIT_GET()' (*note IGRAPH_VIT_GET --- Query the
current position_::) gives the current vertex pointed to by the
iterator (call this only if `IGRAPH_VIT_END()' (*note IGRAPH_VIT_END
--- Are we at the end?::) is false).
Here is an example on how to step over the neighbors of vertex 0:
igraph_vs_t vs;
igraph_vit_t vit;
...
igraph_vs_adj(&vs, 0, IGRAPH_ALL);
igraph_vit_create(&graph, vs, &vit);
while (!IGRAPH_VIT_END(vit)) {
printf(" %li", (long int) IGRAPH_VIT_GET(vit));
IGRAPH_VIT_NEXT(vit);
}
printf("\n");
...
igraph_vit_destroy(&vit);
igraph_vs_destroy(&vs);
File: igraph_reference_manual.info, Node: IGRAPH_VIT_NEXT --- Next vertex_, Next: IGRAPH_VIT_END --- Are we at the end?, Prev: Stepping over the vertices, Up: Vertex iterators
11.5.4 IGRAPH_VIT_NEXT -- Next vertex.
--------------------------------------
#define IGRAPH_VIT_NEXT(vit)
Steps the iterator to the next vertex. Only call this function if
`IGRAPH_VIT_END()' (*note IGRAPH_VIT_END --- Are we at the end?::)
returns false.
*Arguments:. *
`vit':
The vertex iterator to step.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_VIT_END --- Are we at the end?, Next: IGRAPH_VIT_SIZE --- Size of a vertex iterator_, Prev: IGRAPH_VIT_NEXT --- Next vertex_, Up: Vertex iterators
11.5.5 IGRAPH_VIT_END -- Are we at the end?
-------------------------------------------
#define IGRAPH_VIT_END(vit)
Checks whether there are more vertices to step to.
*Arguments:. *
`vit':
The vertex iterator to check.
*Returns:. *
`'
Logical value, if true there are no more vertices to step to.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_VIT_SIZE --- Size of a vertex iterator_, Next: IGRAPH_VIT_RESET --- Reset a vertex iterator_, Prev: IGRAPH_VIT_END --- Are we at the end?, Up: Vertex iterators
11.5.6 IGRAPH_VIT_SIZE -- Size of a vertex iterator.
----------------------------------------------------
#define IGRAPH_VIT_SIZE(vit)
Gives the number of vertices in a vertex iterator.
*Arguments:. *
`vit':
The vertex iterator.
*Returns:. *
`'
The number of vertices.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_VIT_RESET --- Reset a vertex iterator_, Next: IGRAPH_VIT_GET --- Query the current position_, Prev: IGRAPH_VIT_SIZE --- Size of a vertex iterator_, Up: Vertex iterators
11.5.7 IGRAPH_VIT_RESET -- Reset a vertex iterator.
---------------------------------------------------
#define IGRAPH_VIT_RESET(vit)
Resets a vertex iterator. After calling this macro the iterator will
point to the first vertex.
*Arguments:. *
`vit':
The vertex iterator.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_VIT_GET --- Query the current position_, Prev: IGRAPH_VIT_RESET --- Reset a vertex iterator_, Up: Vertex iterators
11.5.8 IGRAPH_VIT_GET -- Query the current position.
----------------------------------------------------
#define IGRAPH_VIT_GET(vit)
Gives the vertex id of the current vertex pointed to by the iterator.
*Arguments:. *
`vit':
The vertex iterator.
*Returns:. *
`'
The vertex id of the current vertex.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Edge selector constructors, Next: Immediate edge selectors, Prev: Vertex iterators, Up: Vertex and Edge Selectors and Sequences; Iterators
11.6 Edge selector constructors
===============================
* Menu:
* igraph_es_all --- Edge set, all edges.: igraph_es_all --- Edge set; all edges_.
* igraph_es_incident --- Edges incident on a given vertex.: igraph_es_incident --- Edges incident on a given vertex_.
* igraph_es_none --- Empty edge selector.: igraph_es_none --- Empty edge selector_.
* igraph_es_1 --- Edge selector containing a single edge.: igraph_es_1 --- Edge selector containing a single edge_.
* igraph_es_vector --- Handle a vector as an edge selector.: igraph_es_vector --- Handle a vector as an edge selector_.
* igraph_es_fromto --- Edge selector, all edges between two vertex sets.: igraph_es_fromto --- Edge selector; all edges between two vertex sets_.
* igraph_es_seq --- Edge selector, a sequence of edge ids.: igraph_es_seq --- Edge selector; a sequence of edge ids_.
* igraph_es_pairs --- Edge selector, multiple edges defined by their endpoints in a vector.: igraph_es_pairs --- Edge selector; multiple edges defined by their endpoints in a vector_.
* igraph_es_pairs_small --- Edge selector, multiple edges defined by their endpoints as arguments.: igraph_es_pairs_small --- Edge selector; multiple edges defined by their endpoints as arguments_.
* igraph_es_vector_copy --- Edge set, based on a vector, with copying.: igraph_es_vector_copy --- Edge set; based on a vector; with copying_.
File: igraph_reference_manual.info, Node: igraph_es_all --- Edge set; all edges_, Next: igraph_es_incident --- Edges incident on a given vertex_, Up: Edge selector constructors
11.6.1 igraph_es_all -- Edge set, all edges.
--------------------------------------------
int igraph_es_all(igraph_es_t *es,
igraph_edgeorder_type_t order);
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`order':
Constant giving the order in which the edges will be included in
the selector. Possible values: `IGRAPH_EDGEORDER_ID', edge id
order. `IGRAPH_EDGEORDER_FROM', vertex id order, the id of the
_source_ vertex counts for directed graphs. The order of the
incident edges of a given vertex is arbitrary.
`IGRAPH_EDGEORDER_TO', vertex id order, the id of the _target_
vertex counts for directed graphs. The order of the incident edges
of a given vertex is arbitrary. For undirected graph the latter
two is the same.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ess_all()' (*note igraph_ess_all --- Edge set; all edges
[immediate version]::), `igraph_es_destroy()' (*note
igraph_es_destroy --- Destroys an edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_incident --- Edges incident on a given vertex_, Next: igraph_es_none --- Empty edge selector_, Prev: igraph_es_all --- Edge set; all edges_, Up: Edge selector constructors
11.6.2 igraph_es_incident -- Edges incident on a given vertex.
--------------------------------------------------------------
int igraph_es_incident(igraph_es_t *es,
igraph_integer_t vid, igraph_neimode_t mode);
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`vid':
Vertex id, of which the incident edges will be selected.
`mode':
Constant giving the type of the incident edges to select. This is
ignored for undirected graphs. Possible values: `IGRAPH_OUT',
outgoing edges; `IGRAPH_IN', incoming edges; `IGRAPH_ALL', all
edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_es_destroy()' (*note igraph_es_destroy --- Destroys an
edge selector object_::)
Time complexity: O(1).
* File examples/simple/igraph_es_adj.c*
File: igraph_reference_manual.info, Node: igraph_es_none --- Empty edge selector_, Next: igraph_es_1 --- Edge selector containing a single edge_, Prev: igraph_es_incident --- Edges incident on a given vertex_, Up: Edge selector constructors
11.6.3 igraph_es_none -- Empty edge selector.
---------------------------------------------
int igraph_es_none(igraph_es_t *es);
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object to initialize.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ess_none()' (*note igraph_ess_none --- Immediate empty
edge selector_::), `igraph_es_destroy()' (*note igraph_es_destroy
--- Destroys an edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_1 --- Edge selector containing a single edge_, Next: igraph_es_vector --- Handle a vector as an edge selector_, Prev: igraph_es_none --- Empty edge selector_, Up: Edge selector constructors
11.6.4 igraph_es_1 -- Edge selector containing a single edge.
-------------------------------------------------------------
int igraph_es_1(igraph_es_t *es, igraph_integer_t eid);
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`eid':
Edge id of the edge to select.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ess_1()' (*note igraph_ess_1 --- Immediate version of the
single edge edge selector_::), `igraph_es_destroy()' (*note
igraph_es_destroy --- Destroys an edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_vector --- Handle a vector as an edge selector_, Next: igraph_es_fromto --- Edge selector; all edges between two vertex sets_, Prev: igraph_es_1 --- Edge selector containing a single edge_, Up: Edge selector constructors
11.6.5 igraph_es_vector -- Handle a vector as an edge selector.
---------------------------------------------------------------
int igraph_es_vector(igraph_es_t *es,
const igraph_vector_t *v);
Creates an edge selector which serves as a view to a vector
containing edge ids. Do not destroy the vector before destroying the
view. Many views can be created to the same vector.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector.
`v':
Vector containing edge ids.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ess_vector()' (*note igraph_ess_vector --- Immediate
vector view edge selector_::), `igraph_es_destroy()' (*note
igraph_es_destroy --- Destroys an edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_fromto --- Edge selector; all edges between two vertex sets_, Next: igraph_es_seq --- Edge selector; a sequence of edge ids_, Prev: igraph_es_vector --- Handle a vector as an edge selector_, Up: Edge selector constructors
11.6.6 igraph_es_fromto -- Edge selector, all edges between two vertex sets.
----------------------------------------------------------------------------
int igraph_es_fromto(igraph_es_t *es,
igraph_vs_t from, igraph_vs_t to);
This function is not implemented yet.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector.
`from':
Vertex selector, their outgoing edges will be selected.
`to':
Vertex selector, their incoming edges will be selected from the
previous selection.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_es_destroy()' (*note igraph_es_destroy --- Destroys an
edge selector object_::)
Time complexity: O(1).
* File examples/simple/igraph_es_fromto.c*
File: igraph_reference_manual.info, Node: igraph_es_seq --- Edge selector; a sequence of edge ids_, Next: igraph_es_pairs --- Edge selector; multiple edges defined by their endpoints in a vector_, Prev: igraph_es_fromto --- Edge selector; all edges between two vertex sets_, Up: Edge selector constructors
11.6.7 igraph_es_seq -- Edge selector, a sequence of edge ids.
--------------------------------------------------------------
int igraph_es_seq(igraph_es_t *es,
igraph_integer_t from, igraph_integer_t to);
All edge ids between ` from' and ` to' will be included in the
edge selection.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`from':
The first edge id to be included.
`to':
The last edge id to be included.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_ess_seq()' (*note igraph_ess_seq --- Immediate version of
the sequence edge selector_::), `igraph_es_destroy()' (*note
igraph_es_destroy --- Destroys an edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_pairs --- Edge selector; multiple edges defined by their endpoints in a vector_, Next: igraph_es_pairs_small --- Edge selector; multiple edges defined by their endpoints as arguments_, Prev: igraph_es_seq --- Edge selector; a sequence of edge ids_, Up: Edge selector constructors
11.6.8 igraph_es_pairs -- Edge selector, multiple edges defined by their endpoints in a vector.
-----------------------------------------------------------------------------------------------
int igraph_es_pairs(igraph_es_t *es, const igraph_vector_t *v,
igraph_bool_t directed);
The edges between the given pairs of vertices will be included in the
edge selection. The vertex pairs must be defined in the vector ` v' ,
the first element of the vector is the first vertex of the first edge
to be selected, the second element is the second vertex of the first
edge, the third element is the first vertex of the second edge and so
on.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`v':
The vector containing the endpoints of the edges.
`directed':
Whether the graph is directed or not.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_es_pairs_small()' (*note igraph_es_pairs_small --- Edge
selector; multiple edges defined by their endpoints as
arguments_::), `igraph_es_destroy()' (*note igraph_es_destroy ---
Destroys an edge selector object_::)
Time complexity: O(n), the number of edges being selected.
* File examples/simple/igraph_es_pairs.c*
File: igraph_reference_manual.info, Node: igraph_es_pairs_small --- Edge selector; multiple edges defined by their endpoints as arguments_, Next: igraph_es_vector_copy --- Edge set; based on a vector; with copying_, Prev: igraph_es_pairs --- Edge selector; multiple edges defined by their endpoints in a vector_, Up: Edge selector constructors
11.6.9 igraph_es_pairs_small -- Edge selector, multiple edges defined by their endpoints as arguments.
------------------------------------------------------------------------------------------------------
int igraph_es_pairs_small(igraph_es_t *es, igraph_bool_t directed, ...);
The edges between the given pairs of vertices will be included in the
edge selection. The vertex pairs must be given as the arguments of the
function call, the third argument is the first vertex of the first edge,
the fourth argument is the second vertex of the first edge, the fifth
is the first vertex of the second edge and so on. The last element of
the argument list must be -1 to denote the end of the argument list.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector object.
`directed':
Whether the graph is directed or not.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_es_pairs()' (*note igraph_es_pairs --- Edge selector;
multiple edges defined by their endpoints in a vector_::),
`igraph_es_destroy()' (*note igraph_es_destroy --- Destroys an
edge selector object_::)
Time complexity: O(n), the number of edges being selected.
File: igraph_reference_manual.info, Node: igraph_es_vector_copy --- Edge set; based on a vector; with copying_, Prev: igraph_es_pairs_small --- Edge selector; multiple edges defined by their endpoints as arguments_, Up: Edge selector constructors
11.6.10 igraph_es_vector_copy -- Edge set, based on a vector, with copying.
---------------------------------------------------------------------------
int igraph_es_vector_copy(igraph_es_t *es, const igraph_vector_t *v);
This function makes it possible to handle a `vector_t' permanently
as an edge selector. The edge selector creates a copy of the original
vector, so the vector can safely be destroyed after creating the edge
selector. Changing the original vector will not affect the edge
selector. The edge selector is responsible for deleting the copy made
by itself.
*Arguments:. *
`es':
Pointer to an uninitialized edge selector.
`v':
Pointer to a `igraph_vector_t' object.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_es_destroy()' (*note igraph_es_destroy --- Destroys an
edge selector object_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Immediate edge selectors, Next: Generic edge selector operations, Prev: Edge selector constructors, Up: Vertex and Edge Selectors and Sequences; Iterators
11.7 Immediate edge selectors
=============================
* Menu:
* igraph_ess_all --- Edge set, all edges (immediate version): igraph_ess_all --- Edge set; all edges [immediate version].
* igraph_ess_none --- Immediate empty edge selector.: igraph_ess_none --- Immediate empty edge selector_.
* igraph_ess_1 --- Immediate version of the single edge edge selector.: igraph_ess_1 --- Immediate version of the single edge edge selector_.
* igraph_ess_vector --- Immediate vector view edge selector.: igraph_ess_vector --- Immediate vector view edge selector_.
* igraph_ess_seq --- Immediate version of the sequence edge selector.: igraph_ess_seq --- Immediate version of the sequence edge selector_.
File: igraph_reference_manual.info, Node: igraph_ess_all --- Edge set; all edges [immediate version], Next: igraph_ess_none --- Immediate empty edge selector_, Up: Immediate edge selectors
11.7.1 igraph_ess_all -- Edge set, all edges (immediate version)
----------------------------------------------------------------
igraph_es_t igraph_ess_all(igraph_edgeorder_type_t order);
The immediate version of the all-vertices selector.
*Arguments:. *
`order':
Constant giving the order of the edges in the edge selector. See
`igraph_es_all()' (*note igraph_es_all --- Edge set; all edges_::)
for the possible values.
*Returns:. *
`'
The edge selector.
*See also:. *
`'
`igraph_es_all()' (*note igraph_es_all --- Edge set; all edges_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_ess_none --- Immediate empty edge selector_, Next: igraph_ess_1 --- Immediate version of the single edge edge selector_, Prev: igraph_ess_all --- Edge set; all edges [immediate version], Up: Immediate edge selectors
11.7.2 igraph_ess_none -- Immediate empty edge selector.
--------------------------------------------------------
igraph_es_t igraph_ess_none(void);
Immediate version of the empty edge selector.
*Returns:. *
`'
Initialized empty edge selector.
*See also:. *
`'
`igraph_es_none()' (*note igraph_es_none --- Empty edge
selector_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_ess_1 --- Immediate version of the single edge edge selector_, Next: igraph_ess_vector --- Immediate vector view edge selector_, Prev: igraph_ess_none --- Immediate empty edge selector_, Up: Immediate edge selectors
11.7.3 igraph_ess_1 -- Immediate version of the single edge edge selector.
--------------------------------------------------------------------------
igraph_es_t igraph_ess_1(igraph_integer_t eid);
*Arguments:. *
`eid':
The id of the edge.
*Returns:. *
`'
The edge selector.
*See also:. *
`'
`igraph_es_1()' (*note igraph_es_1 --- Edge selector containing a
single edge_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_ess_vector --- Immediate vector view edge selector_, Next: igraph_ess_seq --- Immediate version of the sequence edge selector_, Prev: igraph_ess_1 --- Immediate version of the single edge edge selector_, Up: Immediate edge selectors
11.7.4 igraph_ess_vector -- Immediate vector view edge selector.
----------------------------------------------------------------
igraph_es_t igraph_ess_vector(const igraph_vector_t *v);
This is the immediate version of the vector of edge ids edge
selector.
*Arguments:. *
`v':
The vector of edge ids.
*Returns:. *
`'
Edge selector, initialized.
*See also:. *
`'
`igraph_es_vector()' (*note igraph_es_vector --- Handle a vector
as an edge selector_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_ess_seq --- Immediate version of the sequence edge selector_, Prev: igraph_ess_vector --- Immediate vector view edge selector_, Up: Immediate edge selectors
11.7.5 igraph_ess_seq -- Immediate version of the sequence edge selector.
-------------------------------------------------------------------------
igraph_es_t igraph_ess_seq(igraph_integer_t from, igraph_integer_t to);
*Arguments:. *
`from':
The first edge id to include.
`to':
The last edge id to include.
*Returns:. *
`'
The initialized edge selector.
*See also:. *
`'
`igraph_es_seq()' (*note igraph_es_seq --- Edge selector; a
sequence of edge ids_::)
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Generic edge selector operations, Next: Edge iterators, Prev: Immediate edge selectors, Up: Vertex and Edge Selectors and Sequences; Iterators
11.8 Generic edge selector operations
=====================================
* Menu:
* igraph_es_copy --- Creates a copy of an edge selector.: igraph_es_copy --- Creates a copy of an edge selector_.
* igraph_es_destroy --- Destroys an edge selector object.: igraph_es_destroy --- Destroys an edge selector object_.
* igraph_es_is_all --- Check whether an edge selector includes all edges.: igraph_es_is_all --- Check whether an edge selector includes all edges_.
* igraph_es_size --- Returns the size of the edge selector.: igraph_es_size --- Returns the size of the edge selector_.
* igraph_es_type --- Returns the type of the edge selector.: igraph_es_type --- Returns the type of the edge selector_.
File: igraph_reference_manual.info, Node: igraph_es_copy --- Creates a copy of an edge selector_, Next: igraph_es_destroy --- Destroys an edge selector object_, Up: Generic edge selector operations
11.8.1 igraph_es_copy -- Creates a copy of an edge selector.
------------------------------------------------------------
int igraph_es_copy(igraph_es_t* dest, const igraph_es_t* src);
*Arguments:. *
`src':
The selector being copied.
`dest':
An uninitialized selector that will contain the copy.
*See also:. *
`'
`igraph_es_destroy()' (*note igraph_es_destroy --- Destroys an
edge selector object_::)
File: igraph_reference_manual.info, Node: igraph_es_destroy --- Destroys an edge selector object_, Next: igraph_es_is_all --- Check whether an edge selector includes all edges_, Prev: igraph_es_copy --- Creates a copy of an edge selector_, Up: Generic edge selector operations
11.8.2 igraph_es_destroy -- Destroys an edge selector object.
-------------------------------------------------------------
void igraph_es_destroy(igraph_es_t *es);
Call this function on an edge selector when it is not needed any
more. Do _not_ call this function on edge selectors created by
immediate constructors, those don't need to be destroyed.
*Arguments:. *
`es':
Pointer to an edge selector object.
Time complexity: operating system dependent, usually O(1).
File: igraph_reference_manual.info, Node: igraph_es_is_all --- Check whether an edge selector includes all edges_, Next: igraph_es_size --- Returns the size of the edge selector_, Prev: igraph_es_destroy --- Destroys an edge selector object_, Up: Generic edge selector operations
11.8.3 igraph_es_is_all -- Check whether an edge selector includes all edges.
-----------------------------------------------------------------------------
igraph_bool_t igraph_es_is_all(const igraph_es_t *es);
*Arguments:. *
`es':
Pointer to an edge selector object.
*Returns:. *
`'
TRUE (1) if ` es' was created with `igraph_es_all()' (*note
igraph_es_all --- Edge set; all edges_::) or `igraph_ess_all()'
(*note igraph_ess_all --- Edge set; all edges [immediate
version]::), and FALSE (0) otherwise.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_es_size --- Returns the size of the edge selector_, Next: igraph_es_type --- Returns the type of the edge selector_, Prev: igraph_es_is_all --- Check whether an edge selector includes all edges_, Up: Generic edge selector operations
11.8.4 igraph_es_size -- Returns the size of the edge selector.
---------------------------------------------------------------
int igraph_es_size(const igraph_t *graph, const igraph_es_t *es,
igraph_integer_t *result);
The size of the edge selector is the number of edges it will yield
when it is iterated over.
*Arguments:. *
`graph':
The graph over which we will iterate.
`result':
The result will be returned here.
File: igraph_reference_manual.info, Node: igraph_es_type --- Returns the type of the edge selector_, Prev: igraph_es_size --- Returns the size of the edge selector_, Up: Generic edge selector operations
11.8.5 igraph_es_type -- Returns the type of the edge selector.
---------------------------------------------------------------
int igraph_es_type(const igraph_es_t *es);
File: igraph_reference_manual.info, Node: Edge iterators, Prev: Generic edge selector operations, Up: Vertex and Edge Selectors and Sequences; Iterators
11.9 Edge iterators
===================
* Menu:
* igraph_eit_create --- Creates an edge iterator from an edge selector.: igraph_eit_create --- Creates an edge iterator from an edge selector_.
* igraph_eit_destroy --- Destroys an edge iterator.: igraph_eit_destroy --- Destroys an edge iterator_.
* Stepping over the edges::
* IGRAPH_EIT_NEXT --- Next edge.: IGRAPH_EIT_NEXT --- Next edge_.
* IGRAPH_EIT_END --- Are we at the end?::
* IGRAPH_EIT_SIZE --- Number of edges in the iterator.: IGRAPH_EIT_SIZE --- Number of edges in the iterator_.
* IGRAPH_EIT_RESET --- Reset an edge iterator.: IGRAPH_EIT_RESET --- Reset an edge iterator_.
* IGRAPH_EIT_GET --- Query an edge iterator.: IGRAPH_EIT_GET --- Query an edge iterator_.
File: igraph_reference_manual.info, Node: igraph_eit_create --- Creates an edge iterator from an edge selector_, Next: igraph_eit_destroy --- Destroys an edge iterator_, Up: Edge iterators
11.9.1 igraph_eit_create -- Creates an edge iterator from an edge selector.
---------------------------------------------------------------------------
int igraph_eit_create(const igraph_t *graph,
igraph_es_t es, igraph_eit_t *eit);
This function creates an edge iterator based on an edge selector and
a graph.
The same edge selector can be used to create many edge iterators,
also for different graphs.
*Arguments:. *
`graph':
An `igraph_t' object for which the edge selector will be
instantiated.
`es':
The edge selector to instantiate.
`eit':
Pointer to an uninitialized edge iterator.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_eit_destroy()' (*note igraph_eit_destroy --- Destroys an
edge iterator_::)
Time complexity: depends on the type of the edge selector. For edge
selectors created by `igraph_es_all()' (*note igraph_es_all --- Edge
set; all edges_::), `igraph_es_none()' (*note igraph_es_none --- Empty
edge selector_::), `igraph_es_1()' (*note igraph_es_1 --- Edge selector
containing a single edge_::), igraph_es_vector(), igraph_es_seq() it is
O(1). For `igraph_es_incident()' (*note igraph_es_incident --- Edges
incident on a given vertex_::) it is O(d) where d is the number of
incident edges of the vertex.
File: igraph_reference_manual.info, Node: igraph_eit_destroy --- Destroys an edge iterator_, Next: Stepping over the edges, Prev: igraph_eit_create --- Creates an edge iterator from an edge selector_, Up: Edge iterators
11.9.2 igraph_eit_destroy -- Destroys an edge iterator.
-------------------------------------------------------
void igraph_eit_destroy(const igraph_eit_t *eit);
*Arguments:. *
`eit':
Pointer to an edge iterator to destroy.
*See also:. *
`'
`igraph_eit_create()' (*note igraph_eit_create --- Creates an edge
iterator from an edge selector_::)
Time complexity: operating system dependent, usually O(1).
File: igraph_reference_manual.info, Node: Stepping over the edges, Next: IGRAPH_EIT_NEXT --- Next edge_, Prev: igraph_eit_destroy --- Destroys an edge iterator_, Up: Edge iterators
11.9.3 Stepping over the edges
------------------------------
Just like for vertex iterators, macros are provided for stepping over a
sequence of edges: `IGRAPH_EIT_NEXT()' (*note IGRAPH_EIT_NEXT --- Next
edge_::) goes to the next edge, `IGRAPH_EIT_END()' (*note
IGRAPH_EIT_END --- Are we at the end?::) checks whether there are more
edges to visit, `IGRAPH_EIT_SIZE()' (*note IGRAPH_EIT_SIZE --- Number
of edges in the iterator_::) gives the number of edges in the edge
sequence, `IGRAPH_EIT_RESET()' (*note IGRAPH_EIT_RESET --- Reset an
edge iterator_::) resets the iterator to the first edge and
`IGRAPH_EIT_GET()' (*note IGRAPH_EIT_GET --- Query an edge iterator_::)
returns the id of the current edge.
File: igraph_reference_manual.info, Node: IGRAPH_EIT_NEXT --- Next edge_, Next: IGRAPH_EIT_END --- Are we at the end?, Prev: Stepping over the edges, Up: Edge iterators
11.9.4 IGRAPH_EIT_NEXT -- Next edge.
------------------------------------
#define IGRAPH_EIT_NEXT(eit)
Steps the iterator to the next edge. Call this function only if
`IGRAPH_EIT_END()' (*note IGRAPH_EIT_END --- Are we at the end?::)
returns false.
*Arguments:. *
`eit':
The edge iterator to step.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_EIT_END --- Are we at the end?, Next: IGRAPH_EIT_SIZE --- Number of edges in the iterator_, Prev: IGRAPH_EIT_NEXT --- Next edge_, Up: Edge iterators
11.9.5 IGRAPH_EIT_END -- Are we at the end?
-------------------------------------------
#define IGRAPH_EIT_END(eit)
Checks whether there are more edges to step to.
*Arguments:. *
`wit':
The edge iterator to check.
*Returns:. *
`'
Logical value, if true there are no more edges to step to.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_EIT_SIZE --- Number of edges in the iterator_, Next: IGRAPH_EIT_RESET --- Reset an edge iterator_, Prev: IGRAPH_EIT_END --- Are we at the end?, Up: Edge iterators
11.9.6 IGRAPH_EIT_SIZE -- Number of edges in the iterator.
----------------------------------------------------------
#define IGRAPH_EIT_SIZE(eit)
Gives the number of edges in an edge iterator.
*Arguments:. *
`eit':
The edge iterator.
*Returns:. *
`'
The number of edges.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_EIT_RESET --- Reset an edge iterator_, Next: IGRAPH_EIT_GET --- Query an edge iterator_, Prev: IGRAPH_EIT_SIZE --- Number of edges in the iterator_, Up: Edge iterators
11.9.7 IGRAPH_EIT_RESET -- Reset an edge iterator.
--------------------------------------------------
#define IGRAPH_EIT_RESET(eit)
Resets an edge iterator. After calling this macro the iterator will
point to the first edge.
*Arguments:. *
`eit':
The edge iterator.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: IGRAPH_EIT_GET --- Query an edge iterator_, Prev: IGRAPH_EIT_RESET --- Reset an edge iterator_, Up: Edge iterators
11.9.8 IGRAPH_EIT_GET -- Query an edge iterator.
------------------------------------------------
#define IGRAPH_EIT_GET(eit)
Gives the edge id of the current edge pointed to by an iterator.
*Arguments:. *
`eit':
The edge iterator.
*Returns:. *
`'
The id of the current edge.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: Graph; Vertex and Edge Attributes, Next: Structural Properties of Graphs, Prev: Vertex and Edge Selectors and Sequences; Iterators, Up: Top
12 Graph, Vertex and Edge Attributes
************************************
Attributes are numbers or strings (or basically any kind of data)
associated with the vertices or edges of a graph, or with the graph
itself. Eg. you may label vertices with symbolic names or attach
numeric weights to the edges of a graph.
igraph attributes are designed to be flexible and extensible. In
igraph attributes are implemented via an interface abstraction: any
type implementing the functions in the interface, can be used for
storing vertex, edge and graph attributes. This means that different
attribute implementations can be used together with igraph. This is
reasonable: if igraph is used from Python attributes can be of any
Python type, from GNU R all R types are allowed. There is an
experimental attribute implementation to be used when programming in C,
but by default it is currently turned off.
First we briefly look over how attribute handlers can be
implemented. This is not something a user does every day. It is rather
typically the job of the high level interface writers. (But it is
possible to write an interface without implementing attributes.) Then
we show the experimental C attribute handler.
* Menu:
* The Attribute Handler Interface::
* Accessing attributes from C::
File: igraph_reference_manual.info, Node: The Attribute Handler Interface, Next: Accessing attributes from C, Up: Graph; Vertex and Edge Attributes
12.1 The Attribute Handler Interface
====================================
It is possible to attach an attribute handling interface to `igraph'.
This is simply a table of functions, of type `igraph_attribute_table_t'
(*note igraph_attribute_table_t --- Table of functions to perform
operations on attributes::). These functions are invoked to notify the
attribute handling code about the structural changes in a graph. See
the documentation of this type for details.
By default there is no attribute interface attached to `igraph', to
attach one, call `igraph_i_set_attribute_table' (*note
igraph_i_set_attribute_table --- Attach an attribute table_::) with
your new table.
* Menu:
* igraph_attribute_table_t --- Table of functions to perform operations on attributes::
* igraph_i_set_attribute_table --- Attach an attribute table.: igraph_i_set_attribute_table --- Attach an attribute table_.
* igraph_attribute_type_t --- The possible types of the attributes. : igraph_attribute_type_t --- The possible types of the attributes_.
File: igraph_reference_manual.info, Node: igraph_attribute_table_t --- Table of functions to perform operations on attributes, Next: igraph_i_set_attribute_table --- Attach an attribute table_, Up: The Attribute Handler Interface
12.1.1 igraph_attribute_table_t -- Table of functions to perform operations on attributes
-----------------------------------------------------------------------------------------
typedef struct igraph_attribute_table_t {
int (*init)(igraph_t *graph, igraph_vector_ptr_t *attr);
void (*destroy)(igraph_t *graph);
int (*copy)(igraph_t *to, const igraph_t *from, igraph_bool_t ga,
igraph_bool_t va, igraph_bool_t ea);
int (*add_vertices)(igraph_t *graph, long int nv, igraph_vector_ptr_t *attr);
int (*permute_vertices)(const igraph_t *graph,
igraph_t *newgraph,
const igraph_vector_t *idx);
int (*combine_vertices)(const igraph_t *graph,
igraph_t *newgraph,
const igraph_vector_ptr_t *merges,
const igraph_attribute_combination_t *comb);
int (*add_edges)(igraph_t *graph, const igraph_vector_t *edges,
igraph_vector_ptr_t *attr);
int (*permute_edges)(const igraph_t *graph,
igraph_t *newgraph, const igraph_vector_t *idx);
int (*combine_edges)(const igraph_t *graph,
igraph_t *newgraph,
const igraph_vector_ptr_t *merges,
const igraph_attribute_combination_t *comb);
int (*get_info)(const igraph_t *graph,
igraph_strvector_t *gnames, igraph_vector_t *gtypes,
igraph_strvector_t *vnames, igraph_vector_t *vtypes,
igraph_strvector_t *enames, igraph_vector_t *etypes);
igraph_bool_t (*has_attr)(const igraph_t *graph, igraph_attribute_elemtype_t type,
const char *name);
int (*gettype)(const igraph_t *graph, igraph_attribute_type_t *type,
igraph_attribute_elemtype_t elemtype, const char *name);
int (*get_numeric_graph_attr)(const igraph_t *graph, const char *name,
igraph_vector_t *value);
int (*get_string_graph_attr)(const igraph_t *graph, const char *name,
igraph_strvector_t *value);
int (*get_bool_graph_attr)(const igraph_t *igraph, const char *name,
igraph_vector_bool_t *value);
int (*get_numeric_vertex_attr)(const igraph_t *graph, const char *name,
igraph_vs_t vs,
igraph_vector_t *value);
int (*get_string_vertex_attr)(const igraph_t *graph, const char *name,
igraph_vs_t vs,
igraph_strvector_t *value);
int (*get_bool_vertex_attr)(const igraph_t *graph, const char *name,
igraph_vs_t vs,
igraph_vector_bool_t *value);
int (*get_numeric_edge_attr)(const igraph_t *graph, const char *name,
igraph_es_t es,
igraph_vector_t *value);
int (*get_string_edge_attr)(const igraph_t *graph, const char *name,
igraph_es_t es,
igraph_strvector_t *value);
int (*get_bool_edge_attr)(const igraph_t *graph, const char *name,
igraph_es_t es,
igraph_vector_bool_t *value);
} igraph_attribute_table_t;
This type collects the functions defining an attribute handler. It
has the following members:
*Values:. *
`init':
This function is called whenever a new graph object is created,
right after it is created but before any vertices or edges are
added. It is supposed to set the `attr' member of the `igraph_t'
object. It is expected to return an error code.
`destroy':
This function is called whenever the graph object is destroyed,
right before freeing the allocated memory.
`copy':
This function is called when copying a graph with `igraph_copy'
(*note igraph_copy --- Creates an exact [deep] copy of a
graph_::), after the structure of the graph has been already
copied. It is expected to return an error code.
`add_vertices':
Called when vertices are added to a graph, before adding the
vertices themselves. The number of vertices to add is supplied as
an argument. Expected to return an error code.
`permute_vertices':
Typically called when a new graph is created based on an existing
one, e.g. if vertices are removed from a graph. The supplied index
vector defines which old vertex a new vertex corresponds to. Its
length must be the same as the number of vertices in the new graph.
`combine_vertices':
This function is called when the creation of a new graph involves
a merge (contraction, etc.) of vertices from another graph. The
function is after the new graph was created. An argument
specifies how several vertices from the old graph map to a single
vertex in the new graph.
`add_edges':
Called when new edges have been added. The number of new edges are
supplied as well. It is expected to return an error code.
`permute_edges':
Typically called when a new graph is created and some of the new
edges should carry the attributes of some of the old edges. The
idx vector shows the mapping between the old edges and the new
ones. Its length is the same as the number of edges in the new
graph, and for each edge it gives the id of the old edge (the edge
in the old graph).
`combine_edges':
This function is called when the creation of a new graph involves
a merge (contraction, etc.) of edges from another graph. The
function is after the new graph was created. An argument
specifies how several edges from the old graph map to a single
edge in the new graph.
`get_info':
Query the attributes of a graph, the names and types should be
returned.
`has_attr':
Check whether a graph has the named graph/vertex/edge attribute.
`gettype':
Query the type of a graph/vertex/edge attribute.
`get_numeric_graph_attr':
Query a numeric graph attribute. The value should be placed as the
first element of the `value' vector.
`get_string_graph_attr':
Query a string graph attribute. The value should be placed as the
first element of the `value' string vector.
`get_bool_graph_attr':
Query a boolean graph attribute. The value should be placed as the
first element of the `value' boolean vector.
`get_numeric_vertex_attr':
Query a numeric vertex attribute, for the vertices included in
`vs'.
`get_string_vertex_attr':
Query a string vertex attribute, for the vertices included in `vs'.
`get_bool_vertex_attr':
Query a boolean vertex attribute, for the vertices included in
`vs'.
`get_numeric_edge_attr':
Query a numeric edge attribute, for the edges included in `es'.
`get_string_edge_attr':
Query a string edge attribute, for the edges included in `es'.
`get_bool_edge_attr':
Query a boolean edge attribute, for the edges included in `es'.
Note that the `get_*_*_attr' are allowed to convert the attributes
to numeric or string. E.g. if a vertex attribute is a GNU R complex
data type, then `get_string_vertex_attribute' may serialize it into a
string, but this probably makes sense only if `add_vertices' is able to
deserialize it.
File: igraph_reference_manual.info, Node: igraph_i_set_attribute_table --- Attach an attribute table_, Next: igraph_attribute_type_t --- The possible types of the attributes_, Prev: igraph_attribute_table_t --- Table of functions to perform operations on attributes, Up: The Attribute Handler Interface
12.1.2 igraph_i_set_attribute_table -- Attach an attribute table.
-----------------------------------------------------------------
igraph_attribute_table_t *
igraph_i_set_attribute_table(const igraph_attribute_table_t * table);
This function attaches attribute handling code to the igraph library.
Note that the attribute handler table is _not_ thread-local even if
igraph is compiled in thread-local mode. In the vast majority of cases,
this is not a significant restriction.
*Arguments:. *
`table':
Pointer to an `igraph_attribute_table_t' (*note
igraph_attribute_table_t --- Table of functions to perform
operations on attributes::) object containing the functions for
attribute manipulation. Supply `NULL' here if you don't want
attributes.
*Returns:. *
`'
Pointer to the old attribute handling table.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_attribute_type_t --- The possible types of the attributes_, Prev: igraph_i_set_attribute_table --- Attach an attribute table_, Up: The Attribute Handler Interface
12.1.3 igraph_attribute_type_t -- The possible types of the attributes.
-----------------------------------------------------------------------
typedef enum { IGRAPH_ATTRIBUTE_DEFAULT=0,
IGRAPH_ATTRIBUTE_NUMERIC=1,
IGRAPH_ATTRIBUTE_BOOLEAN=5,
IGRAPH_ATTRIBUTE_STRING=2,
IGRAPH_ATTRIBUTE_R_OBJECT=3,
IGRAPH_ATTRIBUTE_PY_OBJECT=4 } igraph_attribute_type_t;
Note that this is only the type communicated by the attribute
interface towards igraph functions. Eg. in the GNU R attribute handler,
it is safe to say that all complex R object attributes are strings, as
long as this interface is able to serialize them into strings. See also
`igraph_attribute_table_t' (*note igraph_attribute_table_t --- Table of
functions to perform operations on attributes::).
*Values:. *
`IGRAPH_ATTRIBUTE_DEFAULT':
Currently not used for anything.
`IGRAPH_ATTRIBUTE_NUMERIC':
Numeric attribute.
`IGRAPH_ATTRIBUTE_BOOLEAN':
Logical values, true or false.
`IGRAPH_ATTRIBUTE_STRING':
Attribute that can be converted to a string.
`IGRAPH_ATTRIBUTE_R_OBJECT':
An R object. This is usually ignored by the igraph functions.
`IGRAPH_ATTRIBUTE_PY_OBJECT':
A Python object. Usually ignored by the igraph functions.
File: igraph_reference_manual.info, Node: Accessing attributes from C, Prev: The Attribute Handler Interface, Up: Graph; Vertex and Edge Attributes
12.2 Accessing attributes from C
================================
There is an experimental attribute handler that can be used from C
code. In this section we show how this works. This attribute handler is
by default not attached (the default is no attribute handler), so we
first need to attach it:
igraph_i_set_attribute_table(&igraph_cattribute_table);
Now the attribute functions are available. Please note that the
attribute handler must be attached before you call any other igraph
functions, otherwise you might end up with graphs without attributes
and an active attribute handler, which might cause unexpected program
behaviour. The rule is that you attach the attribute handler in the
beginning of your `main()' and never touch it again. (Detaching the
attribute handler might lead to memory leaks.)
It is not currently possible to have attribute handlers on a
per-graph basis. All graphs in an application must be managed with the
same attribute handler. (Including the default case when there is no
attribute handler at all.
The C attribute handler supports attaching real numbers and
character strings as attributes. No vectors are allowed, ie. every
vertex might have an attribute called ` name' , but it is not possible
to have a ` coords' graph (or other) attribute which is a vector of
numbers.
* File examples/simple/cattributes.c*
* File examples/simple/cattributes2.c*
* File examples/simple/cattributes3.c*
* File examples/simple/cattributes4.c*
* Menu:
* Query attributes::
* Set attributes::
* Remove attributes::
File: igraph_reference_manual.info, Node: Query attributes, Next: Set attributes, Up: Accessing attributes from C
12.2.1 Query attributes
-----------------------
* Menu:
* igraph_cattribute_list --- List all attributes::
* igraph_cattribute_has_attr --- Checks whether a (graph, vertex or edge) attribute exists: igraph_cattribute_has_attr --- Checks whether a [graph; vertex or edge] attribute exists.
* igraph_cattribute_GAN --- Query a numeric graph attribute.: igraph_cattribute_GAN --- Query a numeric graph attribute_.
* GAN --- Query a numeric graph attribute.: GAN --- Query a numeric graph attribute_.
* igraph_cattribute_GAB --- Query a boolean graph attribute.: igraph_cattribute_GAB --- Query a boolean graph attribute_.
* GAB --- Query a boolean graph attribute.: GAB --- Query a boolean graph attribute_.
* igraph_cattribute_GAS --- Query a string graph attribute.: igraph_cattribute_GAS --- Query a string graph attribute_.
* GAS --- Query a string graph attribute.: GAS --- Query a string graph attribute_.
* igraph_cattribute_VAN --- Query a numeric vertex attribute.: igraph_cattribute_VAN --- Query a numeric vertex attribute_.
* VAN --- Query a numeric vertex attribute.: VAN --- Query a numeric vertex attribute_.
* igraph_cattribute_VANV --- Query a numeric vertex attribute for many vertices::
* VANV --- Query a numeric vertex attribute for all vertices.: VANV --- Query a numeric vertex attribute for all vertices_.
* igraph_cattribute_VAB --- Query a boolean vertex attribute.: igraph_cattribute_VAB --- Query a boolean vertex attribute_.
* VAB --- Query a boolean vertex attribute.: VAB --- Query a boolean vertex attribute_.
* igraph_cattribute_VABV --- Query a boolean vertex attribute for many vertices::
* VABV --- Query a boolean vertex attribute for all vertices.: VABV --- Query a boolean vertex attribute for all vertices_.
* igraph_cattribute_VAS --- Query a string vertex attribute.: igraph_cattribute_VAS --- Query a string vertex attribute_.
* VAS --- Query a string vertex attribute.: VAS --- Query a string vertex attribute_.
* igraph_cattribute_VASV --- Query a string vertex attribute for many vertices::
* VASV --- Query a string vertex attribute for all vertices.: VASV --- Query a string vertex attribute for all vertices_.
* igraph_cattribute_EAN --- Query a numeric edge attribute.: igraph_cattribute_EAN --- Query a numeric edge attribute_.
* EAN --- Query a numeric edge attribute.: EAN --- Query a numeric edge attribute_.
* igraph_cattribute_EANV --- Query a numeric edge attribute for many edges::
* EANV --- Query a numeric edge attribute for all edges.: EANV --- Query a numeric edge attribute for all edges_.
* igraph_cattribute_EAB --- Query a boolean edge attribute.: igraph_cattribute_EAB --- Query a boolean edge attribute_.
* EAB --- Query a boolean edge attribute.: EAB --- Query a boolean edge attribute_.
* igraph_cattribute_EABV --- Query a boolean edge attribute for many edges::
* EABV --- Query a boolean edge attribute for all edges.: EABV --- Query a boolean edge attribute for all edges_.
* igraph_cattribute_EAS --- Query a string edge attribute.: igraph_cattribute_EAS --- Query a string edge attribute_.
* EAS --- Query a string edge attribute.: EAS --- Query a string edge attribute_.
* igraph_cattribute_EASV --- Query a string edge attribute for many edges::
* EASV --- Query a string edge attribute for all edges.: EASV --- Query a string edge attribute for all edges_.
File: igraph_reference_manual.info, Node: igraph_cattribute_list --- List all attributes, Next: igraph_cattribute_has_attr --- Checks whether a [graph; vertex or edge] attribute exists, Up: Query attributes
12.2.1.1 igraph_cattribute_list -- List all attributes
......................................................
int igraph_cattribute_list(const igraph_t *graph,
igraph_strvector_t *gnames, igraph_vector_t *gtypes,
igraph_strvector_t *vnames, igraph_vector_t *vtypes,
igraph_strvector_t *enames, igraph_vector_t *etypes);
See `igraph_attribute_type_t' (*note igraph_attribute_type_t --- The
possible types of the attributes_::) for the various attribute types.
*Arguments:. *
`graph':
The input graph.
`gnames':
String vector, the names of the graph attributes.
`gtypes':
Numeric vector, the types of the graph attributes.
`vnames':
String vector, the names of the vertex attributes.
`vtypes':
Numeric vector, the types of the vertex attributes.
`enames':
String vector, the names of the edge attributes.
`etypes':
Numeric vector, the types of the edge attributes.
*Returns:. *
`'
Error code.
Naturally, the string vector with the attribute names and the
numeric vector with the attribute types are in the right order, i.e.
the first name corresponds to the first type, etc. Time complexity:
O(Ag+Av+Ae), the number of all attributes.
File: igraph_reference_manual.info, Node: igraph_cattribute_has_attr --- Checks whether a [graph; vertex or edge] attribute exists, Next: igraph_cattribute_GAN --- Query a numeric graph attribute_, Prev: igraph_cattribute_list --- List all attributes, Up: Query attributes
12.2.1.2 igraph_cattribute_has_attr -- Checks whether a (graph, vertex or edge) attribute exists
................................................................................................
igraph_bool_t igraph_cattribute_has_attr(const igraph_t *graph,
igraph_attribute_elemtype_t type,
const char *name);
*Arguments:. *
`graph':
The graph.
`type':
The type of the attribute, `IGRAPH_ATTRIBUTE_GRAPH',
`IGRAPH_ATTRIBUTE_VERTEX' or `IGRAPH_ATTRIBUTE_EDGE'.
`name':
Character constant, the name of the attribute.
*Returns:. *
`'
Logical value, TRUE if the attribute exists, FALSE otherwise.
Time complexity: O(A), the number of (graph, vertex or edge)
attributes, assuming attribute names are not too long.
File: igraph_reference_manual.info, Node: igraph_cattribute_GAN --- Query a numeric graph attribute_, Next: GAN --- Query a numeric graph attribute_, Prev: igraph_cattribute_has_attr --- Checks whether a [graph; vertex or edge] attribute exists, Up: Query attributes
12.2.1.3 igraph_cattribute_GAN -- Query a numeric graph attribute.
..................................................................
igraph_real_t igraph_cattribute_GAN(const igraph_t *graph, const char *name);
Returns the value of the given numeric graph attribute. The
attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute to query.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`GAN' (*note GAN --- Query a numeric graph attribute_::) for a
simpler interface.
Time complexity: O(Ag), the number of graph attributes.
File: igraph_reference_manual.info, Node: GAN --- Query a numeric graph attribute_, Next: igraph_cattribute_GAB --- Query a boolean graph attribute_, Prev: igraph_cattribute_GAN --- Query a numeric graph attribute_, Up: Query attributes
12.2.1.4 GAN -- Query a numeric graph attribute.
................................................
#define GAN(graph,n)
This is shorthand for `igraph_cattribute_GAN()' (*note
igraph_cattribute_GAN --- Query a numeric graph attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_GAB --- Query a boolean graph attribute_, Next: GAB --- Query a boolean graph attribute_, Prev: GAN --- Query a numeric graph attribute_, Up: Query attributes
12.2.1.5 igraph_cattribute_GAB -- Query a boolean graph attribute.
..................................................................
igraph_bool_t igraph_cattribute_GAB(const igraph_t *graph, const char *name);
Returns the value of the given numeric graph attribute. The
attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute to query.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`GAB' (*note GAB --- Query a boolean graph attribute_::) for a
simpler interface.
Time complexity: O(Ag), the number of graph attributes.
File: igraph_reference_manual.info, Node: GAB --- Query a boolean graph attribute_, Next: igraph_cattribute_GAS --- Query a string graph attribute_, Prev: igraph_cattribute_GAB --- Query a boolean graph attribute_, Up: Query attributes
12.2.1.6 GAB -- Query a boolean graph attribute.
................................................
#define GAB(graph,n)
This is shorthand for `igraph_cattribute_GAB()' (*note
igraph_cattribute_GAB --- Query a boolean graph attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_GAS --- Query a string graph attribute_, Next: GAS --- Query a string graph attribute_, Prev: GAB --- Query a boolean graph attribute_, Up: Query attributes
12.2.1.7 igraph_cattribute_GAS -- Query a string graph attribute.
.................................................................
const char* igraph_cattribute_GAS(const igraph_t *graph, const char *name);
Returns a `const' pointer to the string graph attribute specified in
`name'. The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute to query.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`GAS' (*note GAS --- Query a string graph attribute_::) for a
simpler interface.
Time complexity: O(Ag), the number of graph attributes.
File: igraph_reference_manual.info, Node: GAS --- Query a string graph attribute_, Next: igraph_cattribute_VAN --- Query a numeric vertex attribute_, Prev: igraph_cattribute_GAS --- Query a string graph attribute_, Up: Query attributes
12.2.1.8 GAS -- Query a string graph attribute.
...............................................
#define GAS(graph,n)
This is shorthand for `igraph_cattribute_GAS()' (*note
igraph_cattribute_GAS --- Query a string graph attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAN --- Query a numeric vertex attribute_, Next: VAN --- Query a numeric vertex attribute_, Prev: GAS --- Query a string graph attribute_, Up: Query attributes
12.2.1.9 igraph_cattribute_VAN -- Query a numeric vertex attribute.
...................................................................
igraph_real_t igraph_cattribute_VAN(const igraph_t *graph, const char *name,
igraph_integer_t vid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vid':
The id of the queried vertex.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`VAN' (*note VAN --- Query a numeric vertex attribute_::) macro
for a simpler interface.
Time complexity: O(Av), the number of vertex attributes.
File: igraph_reference_manual.info, Node: VAN --- Query a numeric vertex attribute_, Next: igraph_cattribute_VANV --- Query a numeric vertex attribute for many vertices, Prev: igraph_cattribute_VAN --- Query a numeric vertex attribute_, Up: Query attributes
12.2.1.10 VAN -- Query a numeric vertex attribute.
..................................................
#define VAN(graph,n,v)
This is shorthand for `igraph_cattribute_VAN()' (*note
igraph_cattribute_VAN --- Query a numeric vertex attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
The id of the vertex.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_VANV --- Query a numeric vertex attribute for many vertices, Next: VANV --- Query a numeric vertex attribute for all vertices_, Prev: VAN --- Query a numeric vertex attribute_, Up: Query attributes
12.2.1.11 igraph_cattribute_VANV -- Query a numeric vertex attribute for many vertices
......................................................................................
int igraph_cattribute_VANV(const igraph_t *graph, const char *name,
igraph_vs_t vids, igraph_vector_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vids':
The vertices to query.
`result':
Pointer to an initialized vector, the result is stored here. It
will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(v), where v is the number of vertices in 'vids'.
File: igraph_reference_manual.info, Node: VANV --- Query a numeric vertex attribute for all vertices_, Next: igraph_cattribute_VAB --- Query a boolean vertex attribute_, Prev: igraph_cattribute_VANV --- Query a numeric vertex attribute for many vertices, Up: Query attributes
12.2.1.12 VANV -- Query a numeric vertex attribute for all vertices.
....................................................................
#define VANV(graph,n,vec)
This is a shorthand for `igraph_cattribute_VANV()' (*note
igraph_cattribute_VANV --- Query a numeric vertex attribute for many
vertices::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized vector, the result is stored here. It
will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAB --- Query a boolean vertex attribute_, Next: VAB --- Query a boolean vertex attribute_, Prev: VANV --- Query a numeric vertex attribute for all vertices_, Up: Query attributes
12.2.1.13 igraph_cattribute_VAB -- Query a boolean vertex attribute.
....................................................................
igraph_bool_t igraph_cattribute_VAB(const igraph_t *graph, const char *name,
igraph_integer_t vid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vid':
The id of the queried vertex.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`VAB' (*note VAB --- Query a boolean vertex attribute_::) macro
for a simpler interface.
Time complexity: O(Av), the number of vertex attributes.
File: igraph_reference_manual.info, Node: VAB --- Query a boolean vertex attribute_, Next: igraph_cattribute_VABV --- Query a boolean vertex attribute for many vertices, Prev: igraph_cattribute_VAB --- Query a boolean vertex attribute_, Up: Query attributes
12.2.1.14 VAB -- Query a boolean vertex attribute.
..................................................
#define VAB(graph,n,v)
This is shorthand for `igraph_cattribute_VAB()' (*note
igraph_cattribute_VAB --- Query a boolean vertex attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
The id of the vertex.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_VABV --- Query a boolean vertex attribute for many vertices, Next: VABV --- Query a boolean vertex attribute for all vertices_, Prev: VAB --- Query a boolean vertex attribute_, Up: Query attributes
12.2.1.15 igraph_cattribute_VABV -- Query a boolean vertex attribute for many vertices
......................................................................................
int igraph_cattribute_VABV(const igraph_t *graph, const char *name,
igraph_vs_t vids, igraph_vector_bool_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vids':
The vertices to query.
`result':
Pointer to an initialized boolean vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(v), where v is the number of vertices in 'vids'.
File: igraph_reference_manual.info, Node: VABV --- Query a boolean vertex attribute for all vertices_, Next: igraph_cattribute_VAS --- Query a string vertex attribute_, Prev: igraph_cattribute_VABV --- Query a boolean vertex attribute for many vertices, Up: Query attributes
12.2.1.16 VABV -- Query a boolean vertex attribute for all vertices.
....................................................................
#define VABV(graph,n,vec)
This is a shorthand for `igraph_cattribute_VABV()' (*note
igraph_cattribute_VABV --- Query a boolean vertex attribute for many
vertices::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized boolean vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAS --- Query a string vertex attribute_, Next: VAS --- Query a string vertex attribute_, Prev: VABV --- Query a boolean vertex attribute for all vertices_, Up: Query attributes
12.2.1.17 igraph_cattribute_VAS -- Query a string vertex attribute.
...................................................................
const char* igraph_cattribute_VAS(const igraph_t *graph, const char *name,
igraph_integer_t vid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vid':
The id of the queried vertex.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
The macro `VAS' (*note VAS --- Query a string vertex attribute_::)
for a simpler interface.
Time complexity: O(Av), the number of vertex attributes.
File: igraph_reference_manual.info, Node: VAS --- Query a string vertex attribute_, Next: igraph_cattribute_VASV --- Query a string vertex attribute for many vertices, Prev: igraph_cattribute_VAS --- Query a string vertex attribute_, Up: Query attributes
12.2.1.18 VAS -- Query a string vertex attribute.
.................................................
#define VAS(graph,n,v)
This is shorthand for `igraph_cattribute_VAS()' (*note
igraph_cattribute_VAS --- Query a string vertex attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
The id of the vertex.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_VASV --- Query a string vertex attribute for many vertices, Next: VASV --- Query a string vertex attribute for all vertices_, Prev: VAS --- Query a string vertex attribute_, Up: Query attributes
12.2.1.19 igraph_cattribute_VASV -- Query a string vertex attribute for many vertices
.....................................................................................
int igraph_cattribute_VASV(const igraph_t *graph, const char *name,
igraph_vs_t vids, igraph_strvector_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vids':
The vertices to query.
`result':
Pointer to an initialized string vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(v), where v is the number of vertices in 'vids'.
(We assume that the string attributes have a bounded length.)
File: igraph_reference_manual.info, Node: VASV --- Query a string vertex attribute for all vertices_, Next: igraph_cattribute_EAN --- Query a numeric edge attribute_, Prev: igraph_cattribute_VASV --- Query a string vertex attribute for many vertices, Up: Query attributes
12.2.1.20 VASV -- Query a string vertex attribute for all vertices.
...................................................................
#define VASV(graph,n,vec)
This is a shorthand for `igraph_cattribute_VASV()' (*note
igraph_cattribute_VASV --- Query a string vertex attribute for many
vertices::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized string vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAN --- Query a numeric edge attribute_, Next: EAN --- Query a numeric edge attribute_, Prev: VASV --- Query a string vertex attribute for all vertices_, Up: Query attributes
12.2.1.21 igraph_cattribute_EAN -- Query a numeric edge attribute.
..................................................................
igraph_real_t igraph_cattribute_EAN(const igraph_t *graph, const char *name,
igraph_integer_t eid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`eid':
The id of the queried edge.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`EAN' (*note EAN --- Query a numeric edge attribute_::) for an
easier interface.
Time complexity: O(Ae), the number of edge attributes.
File: igraph_reference_manual.info, Node: EAN --- Query a numeric edge attribute_, Next: igraph_cattribute_EANV --- Query a numeric edge attribute for many edges, Prev: igraph_cattribute_EAN --- Query a numeric edge attribute_, Up: Query attributes
12.2.1.22 EAN -- Query a numeric edge attribute.
................................................
#define EAN(graph,n,e)
This is shorthand for `igraph_cattribute_EAN()' (*note
igraph_cattribute_EAN --- Query a numeric edge attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`e':
The id of the edge.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_EANV --- Query a numeric edge attribute for many edges, Next: EANV --- Query a numeric edge attribute for all edges_, Prev: EAN --- Query a numeric edge attribute_, Up: Query attributes
12.2.1.23 igraph_cattribute_EANV -- Query a numeric edge attribute for many edges
.................................................................................
int igraph_cattribute_EANV(const igraph_t *graph, const char *name,
igraph_es_t eids, igraph_vector_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`eids':
The edges to query.
`result':
Pointer to an initialized vector, the result is stored here. It
will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(e), where e is the number of edges in 'eids'.
File: igraph_reference_manual.info, Node: EANV --- Query a numeric edge attribute for all edges_, Next: igraph_cattribute_EAB --- Query a boolean edge attribute_, Prev: igraph_cattribute_EANV --- Query a numeric edge attribute for many edges, Up: Query attributes
12.2.1.24 EANV -- Query a numeric edge attribute for all edges.
...............................................................
#define EANV(graph,n,vec)
This is a shorthand for `igraph_cattribute_EANV()' (*note
igraph_cattribute_EANV --- Query a numeric edge attribute for many
edges::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized vector, the result is stored here. It
will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAB --- Query a boolean edge attribute_, Next: EAB --- Query a boolean edge attribute_, Prev: EANV --- Query a numeric edge attribute for all edges_, Up: Query attributes
12.2.1.25 igraph_cattribute_EAB -- Query a boolean edge attribute.
..................................................................
igraph_bool_t igraph_cattribute_EAB(const igraph_t *graph, const char *name,
igraph_integer_t eid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`eid':
The id of the queried edge.
*Returns:. *
`'
The value of the attribute.
*See also:. *
`'
`EAB' (*note EAB --- Query a boolean edge attribute_::) for an
easier interface.
Time complexity: O(Ae), the number of edge attributes.
File: igraph_reference_manual.info, Node: EAB --- Query a boolean edge attribute_, Next: igraph_cattribute_EABV --- Query a boolean edge attribute for many edges, Prev: igraph_cattribute_EAB --- Query a boolean edge attribute_, Up: Query attributes
12.2.1.26 EAB -- Query a boolean edge attribute.
................................................
#define EAB(graph,n,e)
This is shorthand for `igraph_cattribute_EAB()' (*note
igraph_cattribute_EAB --- Query a boolean edge attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`e':
The id of the edge.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_EABV --- Query a boolean edge attribute for many edges, Next: EABV --- Query a boolean edge attribute for all edges_, Prev: EAB --- Query a boolean edge attribute_, Up: Query attributes
12.2.1.27 igraph_cattribute_EABV -- Query a boolean edge attribute for many edges
.................................................................................
int igraph_cattribute_EABV(const igraph_t *graph, const char *name,
igraph_es_t eids, igraph_vector_bool_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`eids':
The edges to query.
`result':
Pointer to an initialized boolean vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(e), where e is the number of edges in 'eids'.
File: igraph_reference_manual.info, Node: EABV --- Query a boolean edge attribute for all edges_, Next: igraph_cattribute_EAS --- Query a string edge attribute_, Prev: igraph_cattribute_EABV --- Query a boolean edge attribute for many edges, Up: Query attributes
12.2.1.28 EABV -- Query a boolean edge attribute for all edges.
...............................................................
#define EABV(graph,n,vec)
This is a shorthand for `igraph_cattribute_EABV()' (*note
igraph_cattribute_EABV --- Query a boolean edge attribute for many
edges::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized vector, the result is stored here. It
will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAS --- Query a string edge attribute_, Next: EAS --- Query a string edge attribute_, Prev: EABV --- Query a boolean edge attribute for all edges_, Up: Query attributes
12.2.1.29 igraph_cattribute_EAS -- Query a string edge attribute.
.................................................................
const char* igraph_cattribute_EAS(const igraph_t *graph, const char *name,
igraph_integer_t eid);
The attribute must exist, otherwise an error is triggered.
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`eid':
The id of the queried edge.
*Returns:. *
`'
The value of the attribute.
\se `EAS' (*note EAS --- Query a string edge attribute_::) if you
want to type less. Time complexity: O(Ae), the number of edge
attributes.
File: igraph_reference_manual.info, Node: EAS --- Query a string edge attribute_, Next: igraph_cattribute_EASV --- Query a string edge attribute for many edges, Prev: igraph_cattribute_EAS --- Query a string edge attribute_, Up: Query attributes
12.2.1.30 EAS -- Query a string edge attribute.
...............................................
#define EAS(graph,n,e)
This is shorthand for `igraph_cattribute_EAS()' (*note
igraph_cattribute_EAS --- Query a string edge attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`e':
The id of the edge.
*Returns:. *
`'
The value of the attribute.
File: igraph_reference_manual.info, Node: igraph_cattribute_EASV --- Query a string edge attribute for many edges, Next: EASV --- Query a string edge attribute for all edges_, Prev: EAS --- Query a string edge attribute_, Up: Query attributes
12.2.1.31 igraph_cattribute_EASV -- Query a string edge attribute for many edges
................................................................................
int igraph_cattribute_EASV(const igraph_t *graph, const char *name,
igraph_es_t eids, igraph_strvector_t *result);
*Arguments:. *
`graph':
The input graph.
`name':
The name of the attribute.
`vids':
The edges to query.
`result':
Pointer to an initialized string vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
Time complexity: O(e), where e is the number of edges in 'eids'. (We
assume that the string attributes have a bounded length.)
File: igraph_reference_manual.info, Node: EASV --- Query a string edge attribute for all edges_, Prev: igraph_cattribute_EASV --- Query a string edge attribute for many edges, Up: Query attributes
12.2.1.32 EASV -- Query a string edge attribute for all edges.
..............................................................
#define EASV(graph,n,vec)
This is a shorthand for `igraph_cattribute_EASV()' (*note
igraph_cattribute_EASV --- Query a string edge attribute for many
edges::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vec':
Pointer to an initialized string vector, the result is stored
here. It will be resized, if needed.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: Set attributes, Next: Remove attributes, Prev: Query attributes, Up: Accessing attributes from C
12.2.2 Set attributes
---------------------
* Menu:
* igraph_cattribute_GAN_set --- Set a numeric graph attribute::
* SETGAN --- Set a numeric graph attribute::
* igraph_cattribute_GAB_set --- Set a boolean graph attribute::
* SETGAB --- Set a boolean graph attribute::
* igraph_cattribute_GAS_set --- Set a string graph attribute.: igraph_cattribute_GAS_set --- Set a string graph attribute_.
* SETGAS --- Set a string graph attribute::
* igraph_cattribute_VAN_set --- Set a numeric vertex attribute::
* SETVAN --- Set a numeric vertex attribute::
* igraph_cattribute_VAB_set --- Set a boolean vertex attribute::
* SETVAB --- Set a boolean vertex attribute::
* igraph_cattribute_VAS_set --- Set a string vertex attribute::
* SETVAS --- Set a string vertex attribute::
* igraph_cattribute_EAN_set --- Set a numeric edge attribute::
* SETEAN --- Set a numeric edge attribute::
* igraph_cattribute_EAB_set --- Set a boolean edge attribute::
* SETEAB --- Set a boolean edge attribute::
* igraph_cattribute_EAS_set --- Set a string edge attribute::
* SETEAS --- Set a string edge attribute::
* igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all vertices.: igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all vertices_.
* SETVANV --- Set a numeric vertex attribute for all vertices::
* igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all vertices.: igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all vertices_.
* SETVABV --- Set a boolean vertex attribute for all vertices::
* igraph_cattribute_VAS_setv --- Set a string vertex attribute for all vertices.: igraph_cattribute_VAS_setv --- Set a string vertex attribute for all vertices_.
* SETVASV --- Set a string vertex attribute for all vertices::
* igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all vertices.: igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all vertices_.
* SETEANV --- Set a numeric edge attribute for all vertices::
* igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all vertices.: igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all vertices_.
* SETEABV --- Set a boolean edge attribute for all vertices::
* igraph_cattribute_EAS_setv --- Set a string edge attribute for all vertices.: igraph_cattribute_EAS_setv --- Set a string edge attribute for all vertices_.
* SETEASV --- Set a string edge attribute for all vertices::
File: igraph_reference_manual.info, Node: igraph_cattribute_GAN_set --- Set a numeric graph attribute, Next: SETGAN --- Set a numeric graph attribute, Up: Set attributes
12.2.2.1 igraph_cattribute_GAN_set -- Set a numeric graph attribute
...................................................................
int igraph_cattribute_GAN_set(igraph_t *graph, const char *name,
igraph_real_t value);
*Arguments:. *
`graph':
The graph.
`name':
Name of the graph attribute. If there is no such attribute yet,
then it will be added.
`value':
The (new) value of the graph attribute.
*Returns:. *
`'
Error code.
\se `SETGAN' (*note SETGAN --- Set a numeric graph attribute::) if
you want to type less. Time complexity: O(1).
File: igraph_reference_manual.info, Node: SETGAN --- Set a numeric graph attribute, Next: igraph_cattribute_GAB_set --- Set a boolean graph attribute, Prev: igraph_cattribute_GAN_set --- Set a numeric graph attribute, Up: Set attributes
12.2.2.2 SETGAN -- Set a numeric graph attribute
................................................
#define SETGAN(graph,n,value)
This is a shorthand for `igraph_cattribute_GAN_set()' (*note
igraph_cattribute_GAN_set --- Set a numeric graph attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_GAB_set --- Set a boolean graph attribute, Next: SETGAB --- Set a boolean graph attribute, Prev: SETGAN --- Set a numeric graph attribute, Up: Set attributes
12.2.2.3 igraph_cattribute_GAB_set -- Set a boolean graph attribute
...................................................................
int igraph_cattribute_GAB_set(igraph_t *graph, const char *name,
igraph_bool_t value);
*Arguments:. *
`graph':
The graph.
`name':
Name of the graph attribute. If there is no such attribute yet,
then it will be added.
`value':
The (new) value of the graph attribute.
*Returns:. *
`'
Error code.
\se `SETGAN' (*note SETGAN --- Set a numeric graph attribute::) if
you want to type less. Time complexity: O(1).
File: igraph_reference_manual.info, Node: SETGAB --- Set a boolean graph attribute, Next: igraph_cattribute_GAS_set --- Set a string graph attribute_, Prev: igraph_cattribute_GAB_set --- Set a boolean graph attribute, Up: Set attributes
12.2.2.4 SETGAB -- Set a boolean graph attribute
................................................
#define SETGAB(graph,n,value)
This is a shorthand for `igraph_cattribute_GAB_set()' (*note
igraph_cattribute_GAB_set --- Set a boolean graph attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_GAS_set --- Set a string graph attribute_, Next: SETGAS --- Set a string graph attribute, Prev: SETGAB --- Set a boolean graph attribute, Up: Set attributes
12.2.2.5 igraph_cattribute_GAS_set -- Set a string graph attribute.
...................................................................
int igraph_cattribute_GAS_set(igraph_t *graph, const char *name,
const char *value);
*Arguments:. *
`graph':
The graph.
`name':
Name of the graph attribute. If there is no such attribute yet,
then it will be added.
`value':
The (new) value of the graph attribute. It will be copied.
*Returns:. *
`'
Error code.
\se `SETGAS' (*note SETGAS --- Set a string graph attribute::) if
you want to type less. Time complexity: O(1).
File: igraph_reference_manual.info, Node: SETGAS --- Set a string graph attribute, Next: igraph_cattribute_VAN_set --- Set a numeric vertex attribute, Prev: igraph_cattribute_GAS_set --- Set a string graph attribute_, Up: Set attributes
12.2.2.6 SETGAS -- Set a string graph attribute
...............................................
#define SETGAS(graph,n,value)
This is a shorthand for `igraph_cattribute_GAS_set()' (*note
igraph_cattribute_GAS_set --- Set a string graph attribute_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAN_set --- Set a numeric vertex attribute, Next: SETVAN --- Set a numeric vertex attribute, Prev: SETGAS --- Set a string graph attribute, Up: Set attributes
12.2.2.7 igraph_cattribute_VAN_set -- Set a numeric vertex attribute
....................................................................
int igraph_cattribute_VAN_set(igraph_t *graph, const char *name,
igraph_integer_t vid, igraph_real_t value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all vertices included
in `vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`vid':
Vertices for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVAN' (*note SETVAN --- Set a numeric vertex attribute::) for a
simpler way.
Time complexity: O(n), the number of vertices if the attribute is
new, O(|vid|) otherwise.
File: igraph_reference_manual.info, Node: SETVAN --- Set a numeric vertex attribute, Next: igraph_cattribute_VAB_set --- Set a boolean vertex attribute, Prev: igraph_cattribute_VAN_set --- Set a numeric vertex attribute, Up: Set attributes
12.2.2.8 SETVAN -- Set a numeric vertex attribute
.................................................
#define SETVAN(graph,n,vid,value)
This is a shorthand for `igraph_cattribute_VAN_set()' (*note
igraph_cattribute_VAN_set --- Set a numeric vertex attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vid':
Ids of the vertices to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAB_set --- Set a boolean vertex attribute, Next: SETVAB --- Set a boolean vertex attribute, Prev: SETVAN --- Set a numeric vertex attribute, Up: Set attributes
12.2.2.9 igraph_cattribute_VAB_set -- Set a boolean vertex attribute
....................................................................
int igraph_cattribute_VAB_set(igraph_t *graph, const char *name,
igraph_integer_t vid, igraph_bool_t value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all vertices included
in `vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`vid':
Vertices for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVAB' (*note SETVAB --- Set a boolean vertex attribute::) for a
simpler way.
Time complexity: O(n), the number of vertices if the attribute is
new, O(|vid|) otherwise.
File: igraph_reference_manual.info, Node: SETVAB --- Set a boolean vertex attribute, Next: igraph_cattribute_VAS_set --- Set a string vertex attribute, Prev: igraph_cattribute_VAB_set --- Set a boolean vertex attribute, Up: Set attributes
12.2.2.10 SETVAB -- Set a boolean vertex attribute
..................................................
#define SETVAB(graph,n,vid,value)
This is a shorthand for `igraph_cattribute_VAB_set()' (*note
igraph_cattribute_VAB_set --- Set a boolean vertex attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vid':
Ids of the vertices to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAS_set --- Set a string vertex attribute, Next: SETVAS --- Set a string vertex attribute, Prev: SETVAB --- Set a boolean vertex attribute, Up: Set attributes
12.2.2.11 igraph_cattribute_VAS_set -- Set a string vertex attribute
....................................................................
int igraph_cattribute_VAS_set(igraph_t *graph, const char *name,
igraph_integer_t vid, const char *value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all vertices included
in `vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`vid':
Vertices for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVAS' (*note SETVAS --- Set a string vertex attribute::) for a
simpler way.
Time complexity: O(n*l), n is the number of vertices, l is the
length of the string to set. If the attribute if not new then only
O(|vid|*l).
File: igraph_reference_manual.info, Node: SETVAS --- Set a string vertex attribute, Next: igraph_cattribute_EAN_set --- Set a numeric edge attribute, Prev: igraph_cattribute_VAS_set --- Set a string vertex attribute, Up: Set attributes
12.2.2.12 SETVAS -- Set a string vertex attribute
.................................................
#define SETVAS(graph,n,vid,value)
This is a shorthand for `igraph_cattribute_VAS_set()' (*note
igraph_cattribute_VAS_set --- Set a string vertex attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`vid':
Ids of the vertices to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAN_set --- Set a numeric edge attribute, Next: SETEAN --- Set a numeric edge attribute, Prev: SETVAS --- Set a string vertex attribute, Up: Set attributes
12.2.2.13 igraph_cattribute_EAN_set -- Set a numeric edge attribute
...................................................................
int igraph_cattribute_EAN_set(igraph_t *graph, const char *name,
igraph_integer_t eid, igraph_real_t value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all edges included in
`vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`eid':
Edges for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEAN' (*note SETEAN --- Set a numeric edge attribute::) for a
simpler way.
Time complexity: O(e), the number of edges if the attribute is new,
O(|eid|) otherwise.
File: igraph_reference_manual.info, Node: SETEAN --- Set a numeric edge attribute, Next: igraph_cattribute_EAB_set --- Set a boolean edge attribute, Prev: igraph_cattribute_EAN_set --- Set a numeric edge attribute, Up: Set attributes
12.2.2.14 SETEAN -- Set a numeric edge attribute
................................................
#define SETEAN(graph,n,eid,value)
This is a shorthand for `igraph_cattribute_EAN_set()' (*note
igraph_cattribute_EAN_set --- Set a numeric edge attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`eid':
Ids of the edges to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAB_set --- Set a boolean edge attribute, Next: SETEAB --- Set a boolean edge attribute, Prev: SETEAN --- Set a numeric edge attribute, Up: Set attributes
12.2.2.15 igraph_cattribute_EAB_set -- Set a boolean edge attribute
...................................................................
int igraph_cattribute_EAB_set(igraph_t *graph, const char *name,
igraph_integer_t eid, igraph_bool_t value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all edges included in
`vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`eid':
Edges for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEAB' (*note SETEAB --- Set a boolean edge attribute::) for a
simpler way.
Time complexity: O(e), the number of edges if the attribute is new,
O(|eid|) otherwise.
File: igraph_reference_manual.info, Node: SETEAB --- Set a boolean edge attribute, Next: igraph_cattribute_EAS_set --- Set a string edge attribute, Prev: igraph_cattribute_EAB_set --- Set a boolean edge attribute, Up: Set attributes
12.2.2.16 SETEAB -- Set a boolean edge attribute
................................................
#define SETEAB(graph,n,eid,value)
This is a shorthand for `igraph_cattribute_EAB_set()' (*note
igraph_cattribute_EAB_set --- Set a boolean edge attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`eid':
Ids of the edges to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAS_set --- Set a string edge attribute, Next: SETEAS --- Set a string edge attribute, Prev: SETEAB --- Set a boolean edge attribute, Up: Set attributes
12.2.2.17 igraph_cattribute_EAS_set -- Set a string edge attribute
..................................................................
int igraph_cattribute_EAS_set(igraph_t *graph, const char *name,
igraph_integer_t eid, const char *value);
The attribute will be added if not present already. If present it
will be overwritten. The same `value' is set for all edges included in
`vid'.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`eid':
Edges for which to set the attribute.
`value':
The (new) value of the attribute.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEAS' (*note SETEAS --- Set a string edge attribute::) for a
simpler way.
Time complexity: O(e*l), n is the number of edges, l is the length
of the string to set. If the attribute if not new then only O(|eid|*l).
File: igraph_reference_manual.info, Node: SETEAS --- Set a string edge attribute, Next: igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all vertices_, Prev: igraph_cattribute_EAS_set --- Set a string edge attribute, Up: Set attributes
12.2.2.18 SETEAS -- Set a string edge attribute
...............................................
#define SETEAS(graph,n,eid,value)
This is a shorthand for `igraph_cattribute_EAS_set()' (*note
igraph_cattribute_EAS_set --- Set a string edge attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`eid':
Ids of the edges to set.
`value':
The new value of the attribute.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all vertices_, Next: SETVANV --- Set a numeric vertex attribute for all vertices, Prev: SETEAS --- Set a string edge attribute, Up: Set attributes
12.2.2.19 igraph_cattribute_VAN_setv -- Set a numeric vertex attribute for all vertices.
........................................................................................
int igraph_cattribute_VAN_setv(igraph_t *graph, const char *name,
const igraph_vector_t *v);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`v':
The new attribute values. The length of this vector must match the
number of vertices.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVANV' (*note SETVANV --- Set a numeric vertex attribute for
all vertices::) for a simpler way.
Time complexity: O(n), the number of vertices.
File: igraph_reference_manual.info, Node: SETVANV --- Set a numeric vertex attribute for all vertices, Next: igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all vertices_, Prev: igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all vertices_, Up: Set attributes
12.2.2.20 SETVANV -- Set a numeric vertex attribute for all vertices
....................................................................
#define SETVANV(graph,n,v)
This is a shorthand for `igraph_cattribute_VAN_setv()' (*note
igraph_cattribute_VAN_setv --- Set a numeric vertex attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all vertices_, Next: SETVABV --- Set a boolean vertex attribute for all vertices, Prev: SETVANV --- Set a numeric vertex attribute for all vertices, Up: Set attributes
12.2.2.21 igraph_cattribute_VAB_setv -- Set a boolean vertex attribute for all vertices.
........................................................................................
int igraph_cattribute_VAB_setv(igraph_t *graph, const char *name,
const igraph_vector_bool_t *v);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`v':
The new attribute values. The length of this boolean vector must
match the number of vertices.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVANV' (*note SETVANV --- Set a numeric vertex attribute for
all vertices::) for a simpler way.
Time complexity: O(n), the number of vertices.
File: igraph_reference_manual.info, Node: SETVABV --- Set a boolean vertex attribute for all vertices, Next: igraph_cattribute_VAS_setv --- Set a string vertex attribute for all vertices_, Prev: igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all vertices_, Up: Set attributes
12.2.2.22 SETVABV -- Set a boolean vertex attribute for all vertices
....................................................................
#define SETVABV(graph,n,v)
This is a shorthand for `igraph_cattribute_VAB_setv()' (*note
igraph_cattribute_VAB_setv --- Set a boolean vertex attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_VAS_setv --- Set a string vertex attribute for all vertices_, Next: SETVASV --- Set a string vertex attribute for all vertices, Prev: SETVABV --- Set a boolean vertex attribute for all vertices, Up: Set attributes
12.2.2.23 igraph_cattribute_VAS_setv -- Set a string vertex attribute for all vertices.
.......................................................................................
int igraph_cattribute_VAS_setv(igraph_t *graph, const char *name,
const igraph_strvector_t *sv);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`sv':
String vector, the new attribute values. The length of this vector
must match the number of vertices.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETVASV' (*note SETVASV --- Set a string vertex attribute for all
vertices::) for a simpler way.
Time complexity: O(n+l), n is the number of vertices, l is the total
length of the strings.
File: igraph_reference_manual.info, Node: SETVASV --- Set a string vertex attribute for all vertices, Next: igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all vertices_, Prev: igraph_cattribute_VAS_setv --- Set a string vertex attribute for all vertices_, Up: Set attributes
12.2.2.24 SETVASV -- Set a string vertex attribute for all vertices
...................................................................
#define SETVASV(graph,n,v)
This is a shorthand for `igraph_cattribute_VAS_setv()' (*note
igraph_cattribute_VAS_setv --- Set a string vertex attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
*Returns:. *
`'
Error code.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all vertices_, Next: SETEANV --- Set a numeric edge attribute for all vertices, Prev: SETVASV --- Set a string vertex attribute for all vertices, Up: Set attributes
12.2.2.25 igraph_cattribute_EAN_setv -- Set a numeric edge attribute for all vertices.
......................................................................................
int igraph_cattribute_EAN_setv(igraph_t *graph, const char *name,
const igraph_vector_t *v);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`v':
The new attribute values. The length of this vector must match the
number of edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEANV' (*note SETEANV --- Set a numeric edge attribute for all
vertices::) for a simpler way.
Time complexity: O(e), the number of edges.
File: igraph_reference_manual.info, Node: SETEANV --- Set a numeric edge attribute for all vertices, Next: igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all vertices_, Prev: igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all vertices_, Up: Set attributes
12.2.2.26 SETEANV -- Set a numeric edge attribute for all vertices
..................................................................
#define SETEANV(graph,n,v)
This is a shorthand for `igraph_cattribute_EAN_setv()' (*note
igraph_cattribute_EAN_setv --- Set a numeric edge attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all vertices_, Next: SETEABV --- Set a boolean edge attribute for all vertices, Prev: SETEANV --- Set a numeric edge attribute for all vertices, Up: Set attributes
12.2.2.27 igraph_cattribute_EAB_setv -- Set a boolean edge attribute for all vertices.
......................................................................................
int igraph_cattribute_EAB_setv(igraph_t *graph, const char *name,
const igraph_vector_bool_t *v);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`v':
The new attribute values. The length of this vector must match the
number of edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEABV' (*note SETEABV --- Set a boolean edge attribute for all
vertices::) for a simpler way.
Time complexity: O(e), the number of edges.
File: igraph_reference_manual.info, Node: SETEABV --- Set a boolean edge attribute for all vertices, Next: igraph_cattribute_EAS_setv --- Set a string edge attribute for all vertices_, Prev: igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all vertices_, Up: Set attributes
12.2.2.28 SETEABV -- Set a boolean edge attribute for all vertices
..................................................................
#define SETEABV(graph,n,v)
This is a shorthand for `igraph_cattribute_EAB_setv()' (*note
igraph_cattribute_EAB_setv --- Set a boolean edge attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
File: igraph_reference_manual.info, Node: igraph_cattribute_EAS_setv --- Set a string edge attribute for all vertices_, Next: SETEASV --- Set a string edge attribute for all vertices, Prev: SETEABV --- Set a boolean edge attribute for all vertices, Up: Set attributes
12.2.2.29 igraph_cattribute_EAS_setv -- Set a string edge attribute for all vertices.
.....................................................................................
int igraph_cattribute_EAS_setv(igraph_t *graph, const char *name,
const igraph_strvector_t *sv);
The attribute will be added if not present yet.
*Arguments:. *
`graph':
The graph.
`name':
Name of the attribute.
`sv':
String vector, the new attribute values. The length of this vector
must match the number of edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`SETEASV' (*note SETEASV --- Set a string edge attribute for all
vertices::) for a simpler way.
Time complexity: O(e+l), e is the number of edges, l is the total
length of the strings.
File: igraph_reference_manual.info, Node: SETEASV --- Set a string edge attribute for all vertices, Prev: igraph_cattribute_EAS_setv --- Set a string edge attribute for all vertices_, Up: Set attributes
12.2.2.30 SETEASV -- Set a string edge attribute for all vertices
.................................................................
#define SETEASV(graph,n,v)
This is a shorthand for `igraph_cattribute_EAS_setv()' (*note
igraph_cattribute_EAS_setv --- Set a string edge attribute for all
vertices_::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute.
`v':
Vector containing the new values of the attributes.
File: igraph_reference_manual.info, Node: Remove attributes, Prev: Set attributes, Up: Accessing attributes from C
12.2.3 Remove attributes
------------------------
* Menu:
* igraph_cattribute_remove_g --- Remove a graph attribute::
* DELGA --- Remove a graph attribute.: DELGA --- Remove a graph attribute_.
* igraph_cattribute_remove_v --- Remove a vertex attribute::
* DELVA --- Remove a vertex attribute.: DELVA --- Remove a vertex attribute_.
* igraph_cattribute_remove_e --- Remove an edge attribute::
* DELEA --- Remove an edge attribute.: DELEA --- Remove an edge attribute_.
* igraph_cattribute_remove_all --- Remove all graph/vertex/edge attributes::
* DELGAS --- Remove all graph attributes.: DELGAS --- Remove all graph attributes_.
* DELVAS --- Remove all vertex attributes.: DELVAS --- Remove all vertex attributes_.
* DELEAS --- Remove all edge attributes.: DELEAS --- Remove all edge attributes_.
* DELALL --- Remove all attributes.: DELALL --- Remove all attributes_.
File: igraph_reference_manual.info, Node: igraph_cattribute_remove_g --- Remove a graph attribute, Next: DELGA --- Remove a graph attribute_, Up: Remove attributes
12.2.3.1 igraph_cattribute_remove_g -- Remove a graph attribute
...............................................................
void igraph_cattribute_remove_g(igraph_t *graph, const char *name);
*Arguments:. *
`graph':
The graph object.
`name':
Name of the graph attribute to remove.
*See also:. *
`'
`DELGA' (*note DELGA --- Remove a graph attribute_::) for a
simpler way.
File: igraph_reference_manual.info, Node: DELGA --- Remove a graph attribute_, Next: igraph_cattribute_remove_v --- Remove a vertex attribute, Prev: igraph_cattribute_remove_g --- Remove a graph attribute, Up: Remove attributes
12.2.3.2 DELGA -- Remove a graph attribute.
...........................................
#define DELGA(graph,n)
A shorthand for `igraph_cattribute_remove_g()' (*note
igraph_cattribute_remove_g --- Remove a graph attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute to remove.
File: igraph_reference_manual.info, Node: igraph_cattribute_remove_v --- Remove a vertex attribute, Next: DELVA --- Remove a vertex attribute_, Prev: DELGA --- Remove a graph attribute_, Up: Remove attributes
12.2.3.3 igraph_cattribute_remove_v -- Remove a vertex attribute
................................................................
void igraph_cattribute_remove_v(igraph_t *graph, const char *name);
*Arguments:. *
`graph':
The graph object.
`name':
Name of the vertex attribute to remove.
*See also:. *
`'
`DELVA' (*note DELVA --- Remove a vertex attribute_::) for a
simpler way.
File: igraph_reference_manual.info, Node: DELVA --- Remove a vertex attribute_, Next: igraph_cattribute_remove_e --- Remove an edge attribute, Prev: igraph_cattribute_remove_v --- Remove a vertex attribute, Up: Remove attributes
12.2.3.4 DELVA -- Remove a vertex attribute.
............................................
#define DELVA(graph,n)
A shorthand for `igraph_cattribute_remove_v()' (*note
igraph_cattribute_remove_v --- Remove a vertex attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute to remove.
File: igraph_reference_manual.info, Node: igraph_cattribute_remove_e --- Remove an edge attribute, Next: DELEA --- Remove an edge attribute_, Prev: DELVA --- Remove a vertex attribute_, Up: Remove attributes
12.2.3.5 igraph_cattribute_remove_e -- Remove an edge attribute
...............................................................
void igraph_cattribute_remove_e(igraph_t *graph, const char *name);
*Arguments:. *
`graph':
The graph object.
`name':
Name of the edge attribute to remove.
*See also:. *
`'
`DELEA' (*note DELEA --- Remove an edge attribute_::) for a
simpler way.
File: igraph_reference_manual.info, Node: DELEA --- Remove an edge attribute_, Next: igraph_cattribute_remove_all --- Remove all graph/vertex/edge attributes, Prev: igraph_cattribute_remove_e --- Remove an edge attribute, Up: Remove attributes
12.2.3.6 DELEA -- Remove an edge attribute.
...........................................
#define DELEA(graph,n)
A shorthand for `igraph_cattribute_remove_e()' (*note
igraph_cattribute_remove_e --- Remove an edge attribute::).
*Arguments:. *
`graph':
The graph.
`n':
The name of the attribute to remove.
File: igraph_reference_manual.info, Node: igraph_cattribute_remove_all --- Remove all graph/vertex/edge attributes, Next: DELGAS --- Remove all graph attributes_, Prev: DELEA --- Remove an edge attribute_, Up: Remove attributes
12.2.3.7 igraph_cattribute_remove_all -- Remove all graph/vertex/edge attributes
................................................................................
void igraph_cattribute_remove_all(igraph_t *graph, igraph_bool_t g,
igraph_bool_t v, igraph_bool_t e);
*Arguments:. *
`graph':
The graph object.
`g':
Boolean, whether to remove graph attributes.
`v':
Boolean, whether to remove vertex attributes.
`e':
Boolean, whether to remove edge attributes.
*See also:. *
`'
`DELGAS' (*note DELGAS --- Remove all graph attributes_::),
`DELVAS' (*note DELVAS --- Remove all vertex attributes_::),
`DELEAS' (*note DELEAS --- Remove all edge attributes_::),
`DELALL' (*note DELALL --- Remove all attributes_::) for simpler
ways.
File: igraph_reference_manual.info, Node: DELGAS --- Remove all graph attributes_, Next: DELVAS --- Remove all vertex attributes_, Prev: igraph_cattribute_remove_all --- Remove all graph/vertex/edge attributes, Up: Remove attributes
12.2.3.8 DELGAS -- Remove all graph attributes.
...............................................
#define DELGAS(graph)
Calls `igraph_cattribute_remove_all()' (*note
igraph_cattribute_remove_all --- Remove all graph/vertex/edge
attributes::).
*Arguments:. *
`graph':
The graph.
File: igraph_reference_manual.info, Node: DELVAS --- Remove all vertex attributes_, Next: DELEAS --- Remove all edge attributes_, Prev: DELGAS --- Remove all graph attributes_, Up: Remove attributes
12.2.3.9 DELVAS -- Remove all vertex attributes.
................................................
#define DELVAS(graph)
Calls `igraph_cattribute_remove_all()' (*note
igraph_cattribute_remove_all --- Remove all graph/vertex/edge
attributes::).
*Arguments:. *
`graph':
The graph.
File: igraph_reference_manual.info, Node: DELEAS --- Remove all edge attributes_, Next: DELALL --- Remove all attributes_, Prev: DELVAS --- Remove all vertex attributes_, Up: Remove attributes
12.2.3.10 DELEAS -- Remove all edge attributes.
...............................................
#define DELEAS(graph)
Calls `igraph_cattribute_remove_all()' (*note
igraph_cattribute_remove_all --- Remove all graph/vertex/edge
attributes::).
*Arguments:. *
`graph':
The graph.
File: igraph_reference_manual.info, Node: DELALL --- Remove all attributes_, Prev: DELEAS --- Remove all edge attributes_, Up: Remove attributes
12.2.3.11 DELALL -- Remove all attributes.
..........................................
#define DELALL(graph)
All graph, vertex and edges attributes will be removed. Calls
`igraph_cattribute_remove_all()' (*note igraph_cattribute_remove_all
--- Remove all graph/vertex/edge attributes::).
*Arguments:. *
`graph':
The graph.
File: igraph_reference_manual.info, Node: Structural Properties of Graphs, Next: Graph visitors, Prev: Graph; Vertex and Edge Attributes, Up: Top
13 Structural Properties of Graphs
**********************************
These functions usually calculate some structural property of a graph,
like its diameter, the degree of the nodes, etc.
* Menu:
* Basic Properties::
* Shortest Path Related Functions::
* Neighborhood of a vertex::
* Graph Components::
* Degree Sequences::
* Centrality Measures::
* Estimating Centrality Measures::
* Centralization::
* Similarity Measures::
* Spanning Trees::
* Transitivity or Clustering Coefficient::
* Directedness conversion::
* Spectral properties::
* Non-simple graphs; multiple and loop edges::
* Mixing patterns::
* K-Cores::
* Topological sorting, directed acyclic graphs: Topological sorting; directed acyclic graphs.
* Maximum cardinality search, graph decomposition, chordal graphs: Maximum cardinality search; graph decomposition; chordal graphs.
* Matchings::
* Line graphs::
* Unfolding a graph into a tree::
* Other Operations::
File: igraph_reference_manual.info, Node: Basic Properties, Next: Shortest Path Related Functions, Up: Structural Properties of Graphs
13.1 Basic Properties
=====================
* Menu:
* igraph_are_connected --- Decides whether two vertices are connected : igraph_are_connected --- Decides whether two vertices are connected.
File: igraph_reference_manual.info, Node: igraph_are_connected --- Decides whether two vertices are connected, Up: Basic Properties
13.1.1 igraph_are_connected -- Decides whether two vertices are connected
-------------------------------------------------------------------------
int igraph_are_connected(const igraph_t *graph,
igraph_integer_t v1, igraph_integer_t v2,
igraph_bool_t *res);
*Arguments:. *
`graph':
The graph object.
`v1':
The first vertex.
`v2':
The second vertex.
`res':
Boolean, `TRUE' if there is an edge from `v1' to `v2', `FALSE'
otherwise.
*Returns:. *
`'
The error code `IGRAPH_EINVVID' is returned if an invalid vertex
ID is given.
The function is of course symmetric for undirected graphs.
Time complexity: O( min(log(d1), log(d2)) ), d1 is the (out-)degree
of `v1' and d2 is the (in-)degree of `v2'.
File: igraph_reference_manual.info, Node: Shortest Path Related Functions, Next: Neighborhood of a vertex, Prev: Basic Properties, Up: Structural Properties of Graphs
13.2 Shortest Path Related Functions
====================================
* Menu:
* igraph_shortest_paths --- The length of the shortest paths between vertices.: igraph_shortest_paths --- The length of the shortest paths between vertices_.
* igraph_shortest_paths_dijkstra --- Weighted shortest paths from some sources.: igraph_shortest_paths_dijkstra --- Weighted shortest paths from some sources_.
* igraph_shortest_paths_bellman_ford --- Weighted shortest paths from some sources allowing negative weights.: igraph_shortest_paths_bellman_ford --- Weighted shortest paths from some sources allowing negative weights_.
* igraph_shortest_paths_johnson --- Calculate shortest paths from some sources using Johnson's algorithm.: igraph_shortest_paths_johnson --- Calculate shortest paths from some sources using Johnson's algorithm_.
* igraph_get_shortest_paths --- Calculates the shortest paths from/to one vertex.: igraph_get_shortest_paths --- Calculates the shortest paths from/to one vertex_.
* igraph_get_shortest_path --- Shortest path from one vertex to another one.: igraph_get_shortest_path --- Shortest path from one vertex to another one_.
* igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest paths from/to one vertex.: igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest paths from/to one vertex_.
* igraph_get_shortest_path_dijkstra --- Weighted shortest path from one vertex to another one.: igraph_get_shortest_path_dijkstra --- Weighted shortest path from one vertex to another one_.
* igraph_get_all_shortest_paths --- Finds all shortest paths (geodesics) from a vertex to all other vertices.: igraph_get_all_shortest_paths --- Finds all shortest paths [geodesics] from a vertex to all other vertices_.
* igraph_get_all_shortest_paths_dijkstra --- Finds all shortest paths (geodesics) from a vertex to all other vertices.: igraph_get_all_shortest_paths_dijkstra --- Finds all shortest paths [geodesics] from a vertex to all other vertices_.
* igraph_average_path_length --- Calculates the average geodesic length in a graph.: igraph_average_path_length --- Calculates the average geodesic length in a graph_.
* igraph_path_length_hist --- Create a histogram of all shortest path lengths.: igraph_path_length_hist --- Create a histogram of all shortest path lengths_.
* igraph_diameter --- Calculates the diameter of a graph (longest geodesic).: igraph_diameter --- Calculates the diameter of a graph [longest geodesic]_.
* igraph_diameter_dijkstra --- Weighted diameter using Dijkstra's algorithm, non-negative weights only.: igraph_diameter_dijkstra --- Weighted diameter using Dijkstra's algorithm; non-negative weights only_.
* igraph_girth --- The girth of a graph is the length of the shortest circle in it.: igraph_girth --- The girth of a graph is the length of the shortest circle in it_.
* igraph_eccentricity --- Eccentricity of some vertices::
* igraph_radius --- Radius of a graph::
File: igraph_reference_manual.info, Node: igraph_shortest_paths --- The length of the shortest paths between vertices_, Next: igraph_shortest_paths_dijkstra --- Weighted shortest paths from some sources_, Up: Shortest Path Related Functions
13.2.1 igraph_shortest_paths -- The length of the shortest paths between vertices.
----------------------------------------------------------------------------------
int igraph_shortest_paths(const igraph_t *graph, igraph_matrix_t *res,
const igraph_vs_t from, const igraph_vs_t to,
igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph object.
`res':
The result of the calculation, a matrix. A pointer to an
initialized matrix, to be more precise. The matrix will be resized
if needed. It will have the same number of rows as the length of
the `from' argument, and its number of columns is the number of
vertices in the `to' argument. One row of the matrix shows the
distances from/to a given vertex to the ones in `to'. For the
unreachable vertices IGRAPH_INFINITY is returned.
`from':
Vector of the vertex ids for which the path length calculations
are done.
`to':
Vector of the vertex ids to which the path length calculations are
done. It is not allowed to have duplicated vertex ids here.
`mode':
The type of shortest paths to be used for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the lengths of the outgoing paths are calculated.
`IGRAPH_IN '
the lengths of the incoming paths are calculated.
`IGRAPH_ALL '
the directed graph is considered as an undirected one for the
computation.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE '
invalid mode argument.
Time complexity: O(n(|V|+|E|)), n is the number of vertices to
calculate, |V| and |E| are the number of vertices and edges in the
graph.
*See also:. *
`'
`igraph_get_shortest_paths()' (*note igraph_get_shortest_paths ---
Calculates the shortest paths from/to one vertex_::) to get the
paths themselves, `igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) for the weighted version.
File: igraph_reference_manual.info, Node: igraph_shortest_paths_dijkstra --- Weighted shortest paths from some sources_, Next: igraph_shortest_paths_bellman_ford --- Weighted shortest paths from some sources allowing negative weights_, Prev: igraph_shortest_paths --- The length of the shortest paths between vertices_, Up: Shortest Path Related Functions
13.2.2 igraph_shortest_paths_dijkstra -- Weighted shortest paths from some sources.
-----------------------------------------------------------------------------------
int igraph_shortest_paths_dijkstra(const igraph_t *graph,
igraph_matrix_t *res,
const igraph_vs_t from,
const igraph_vs_t to,
const igraph_vector_t *weights,
igraph_neimode_t mode);
This function is Dijkstra's algorithm to find the weighted shortest
paths to all vertices from a single source. (It is run independently
for the given sources.) It uses a binary heap for efficient
implementation.
*Arguments:. *
`graph':
The input graph, can be directed.
`res':
The result, a matrix. A pointer to an initialized matrix should be
passed here. The matrix will be resized as needed. Each row
contains the distances from a single source, to the vertices given
in the `to' argument. Unreachable vertices has distance
`IGRAPH_INFINITY'.
`from':
The source vertices.
`to':
The target vertices. It is not allowed to include a vertex twice
or more.
`weights':
The edge weights. They must be all non-negative for Dijkstra's
algorithm to work. An error code is returned if there is a
negative edge weight in the weight vector. If this is a null
pointer, then the unweighted version, `igraph_shortest_paths()'
(*note igraph_shortest_paths --- The length of the shortest paths
between vertices_::) is called.
`mode':
For directed graphs; whether to follow paths along edge directions
(`IGRAPH_OUT'), or the opposite (`IGRAPH_IN'), or ignore edge
directions completely (`IGRAPH_ALL'). It is ignored for undirected
graphs.
*Returns:. *
`'
Error code.
Time complexity: O(s*|E|log|E|+|V|), where |V| is the number of
vertices, |E| the number of edges and s the number of sources.
*See also:. *
`'
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The
length of the shortest paths between vertices_::) for a (slightly)
faster unweighted version or
`igraph_shortest_paths_bellman_ford()' (*note
igraph_shortest_paths_bellman_ford --- Weighted shortest paths
from some sources allowing negative weights_::) for a weighted
variant that works in the presence of negative edge weights (but no
negative loops).
* File examples/simple/dijkstra.c*
File: igraph_reference_manual.info, Node: igraph_shortest_paths_bellman_ford --- Weighted shortest paths from some sources allowing negative weights_, Next: igraph_shortest_paths_johnson --- Calculate shortest paths from some sources using Johnson's algorithm_, Prev: igraph_shortest_paths_dijkstra --- Weighted shortest paths from some sources_, Up: Shortest Path Related Functions
13.2.3 igraph_shortest_paths_bellman_ford -- Weighted shortest paths from some sources allowing negative weights.
-----------------------------------------------------------------------------------------------------------------
int igraph_shortest_paths_bellman_ford(const igraph_t *graph,
igraph_matrix_t *res,
const igraph_vs_t from,
const igraph_vs_t to,
const igraph_vector_t *weights,
igraph_neimode_t mode);
This function is the Bellman-Ford algorithm to find the weighted
shortest paths to all vertices from a single source. (It is run
independently for the given sources.). If there are no negative
weights, you are better off with `igraph_shortest_paths_dijkstra()'
(*note igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) .
*Arguments:. *
`graph':
The input graph, can be directed.
`res':
The result, a matrix. A pointer to an initialized matrix should be
passed here, the matrix will be resized if needed. Each row
contains the distances from a single source, to all vertices in
the graph, in the order of vertex ids. For unreachable vertices
the matrix contains `IGRAPH_INFINITY'.
`from':
The source vertices.
`weights':
The edge weights. There mustn't be any closed loop in the graph
that has a negative total weight (since this would allow us to
decrease the weight of any path containing at least a single
vertex of this loop infinitely). If this is a null pointer, then
the unweighted version, `igraph_shortest_paths()' (*note
igraph_shortest_paths --- The length of the shortest paths between
vertices_::) is called.
`mode':
For directed graphs; whether to follow paths along edge directions
(`IGRAPH_OUT'), or the opposite (`IGRAPH_IN'), or ignore edge
directions completely (`IGRAPH_ALL'). It is ignored for undirected
graphs.
*Returns:. *
`'
Error code.
Time complexity: O(s*|E|*|V|), where |V| is the number of vertices,
|E| the number of edges and s the number of sources.
*See also:. *
`'
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The
length of the shortest paths between vertices_::) for a faster
unweighted version or `igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) if you do not have negative edge weights.
* File examples/simple/bellman_ford.c*
File: igraph_reference_manual.info, Node: igraph_shortest_paths_johnson --- Calculate shortest paths from some sources using Johnson's algorithm_, Next: igraph_get_shortest_paths --- Calculates the shortest paths from/to one vertex_, Prev: igraph_shortest_paths_bellman_ford --- Weighted shortest paths from some sources allowing negative weights_, Up: Shortest Path Related Functions
13.2.4 igraph_shortest_paths_johnson -- Calculate shortest paths from some sources using Johnson's algorithm.
-------------------------------------------------------------------------------------------------------------
int igraph_shortest_paths_johnson(const igraph_t *graph,
igraph_matrix_t *res,
const igraph_vs_t from,
const igraph_vs_t to,
const igraph_vector_t *weights);
See Wikipedia at http://en.wikipedia.org/wiki/Johnson's_algorithm
(http://en.wikipedia.org/wiki/Johnson's_algorithm) for Johnson's
algorithm. This algorithm works even if the graph contains negative
edge weights, and it is worth using it if we calculate the shortest
paths from many sources.
If no edge weights are supplied, then the unweighted version,
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The length
of the shortest paths between vertices_::) is called.
If all the supplied edge weights are non-negative, then Dijkstra's
algorithm is used by calling `igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from some
sources_::).
*Arguments:. *
`graph':
The input graph, typically it is directed.
`res':
Pointer to an initialized matrix, the result will be stored here,
one line for each source vertex, one column for each target vertex.
`from':
The source vertices.
`to':
The target vertices. It is not allowed to include a vertex twice
or more.
`weights':
Optional edge weights. If it is a null-pointer, then the
unweighted breadth-first search based `igraph_shortest_paths()'
(*note igraph_shortest_paths --- The length of the shortest paths
between vertices_::) will be called.
*Returns:. *
`'
Error code.
Time complexity: O(s|V|log|V|+|V||E|), |V| and |E| are the number of
vertices and edges, s is the number of source vertices.
*See also:. *
`'
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The
length of the shortest paths between vertices_::) for a faster
unweighted version or `igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) if you do not have negative edge weights,
`igraph_shortest_paths_bellman_ford()' (*note
igraph_shortest_paths_bellman_ford --- Weighted shortest paths
from some sources allowing negative weights_::) if you only need
to calculate shortest paths from a couple of sources.
File: igraph_reference_manual.info, Node: igraph_get_shortest_paths --- Calculates the shortest paths from/to one vertex_, Next: igraph_get_shortest_path --- Shortest path from one vertex to another one_, Prev: igraph_shortest_paths_johnson --- Calculate shortest paths from some sources using Johnson's algorithm_, Up: Shortest Path Related Functions
13.2.5 igraph_get_shortest_paths -- Calculates the shortest paths from/to one vertex.
-------------------------------------------------------------------------------------
int igraph_get_shortest_paths(const igraph_t *graph,
igraph_vector_ptr_t *vertices,
igraph_vector_ptr_t *edges,
igraph_integer_t from, const igraph_vs_t to,
igraph_neimode_t mode,
igraph_vector_long_t *predecessors,
igraph_vector_long_t *inbound_edges);
If there is more than one geodesic between two vertices, this
function gives only one of them.
*Arguments:. *
`graph':
The graph object.
`vertices':
The result, the ids of the vertices along the paths. This is a
pointer vector, each element points to a vector object. These
should be initialized before passing them to the function, which
will properly clear and/or resize them and fill the ids of the
vertices along the geodesics from/to the vertices. Supply a null
pointer here if you don't need these vectors.
`edges':
The result, the ids of the edges along the paths. This is a
pointer vector, each element points to a vector object. These
should be initialized before passing them to the function, which
will properly clear and/or resize them and fill the ids of the
vertices along the geodesics from/to the vertices. Supply a null
pointer here if you don't need these vectors.
`from':
The id of the vertex from/to which the geodesics are calculated.
`to':
Vertex sequence with the ids of the vertices to/from which the
shortest paths will be calculated. A vertex might be given multiple
times.
`mode':
The type of shortest paths to be used for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the outgoing paths are calculated.
`IGRAPH_IN '
the incoming paths are calculated.
`IGRAPH_ALL '
the directed graph is considered as an undirected one for the
computation.
`predecessors':
A pointer to an initialized igraph vector or null. If not null, a
vector containing the predecessor of each vertex in the single
source shortest path tree is returned here. The predecessor of
vertex i in the tree is the vertex from which vertex i was
reached. The predecessor of the start vertex (in the `from'
argument) is itself by definition. If the predecessor is -1, it
means that the given vertex was not reached from the source during
the search. Note that the search terminates if all the vertices in
`to' are reached.
`inbound_edges':
A pointer to an initialized igraph vector or null. If not null, a
vector containing the inbound edge of each vertex in the single
source shortest path tree is returned here. The inbound edge of
vertex i in the tree is the edge via which vertex i was reached.
The start vertex and vertices that were not reached during the
search will have -1 in the corresponding entry of the vector. Note
that the search terminates if all the vertices in `to' are reached.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID'
`from' is invalid vertex id, or the length of `to' is not the
same as the length of `res'.
`IGRAPH_EINVMODE '
invalid mode argument.
Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| the
number of edges in the graph.
*See also:. *
`'
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The
length of the shortest paths between vertices_::) if you only need
the path length but not the paths themselves.
* File examples/simple/igraph_get_shortest_paths.c*
File: igraph_reference_manual.info, Node: igraph_get_shortest_path --- Shortest path from one vertex to another one_, Next: igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest paths from/to one vertex_, Prev: igraph_get_shortest_paths --- Calculates the shortest paths from/to one vertex_, Up: Shortest Path Related Functions
13.2.6 igraph_get_shortest_path -- Shortest path from one vertex to another one.
--------------------------------------------------------------------------------
int igraph_get_shortest_path(const igraph_t *graph,
igraph_vector_t *vertices,
igraph_vector_t *edges,
igraph_integer_t from,
igraph_integer_t to,
igraph_neimode_t mode);
Calculates and returns a single unweighted shortest path from a
given vertex to another one. If there are more than one shortest paths
between the two vertices, then an arbitrary one is returned.
This function is a wrapper to `igraph_get_shortest_paths()' (*note
igraph_get_shortest_paths --- Calculates the shortest paths from/to one
vertex_::), for the special case when only one target vertex is
considered.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected. Directed paths
are considered in directed graphs.
`vertices':
Pointer to an initialized vector or a null pointer. If not a null
pointer, then the vertex ids along the path are stored here,
including the source and target vertices.
`edges':
Pointer to an uninitialized vector or a null pointer. If not a
null pointer, then the edge ids along the path are stored here.
`from':
The id of the source vertex.
`to':
The id of the target vertex.
`mode':
A constant specifying how edge directions are considered in
directed graphs. Valid modes are: `IGRAPH_OUT', follows edge
directions; `IGRAPH_IN', follows the opposite directions; and
`IGRAPH_ALL', ignores edge directions. This argument is ignored
for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges in the graph.
*See also:. *
`'
`igraph_get_shortest_paths()' (*note igraph_get_shortest_paths ---
Calculates the shortest paths from/to one vertex_::) for the
version with more target vertices.
File: igraph_reference_manual.info, Node: igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest paths from/to one vertex_, Next: igraph_get_shortest_path_dijkstra --- Weighted shortest path from one vertex to another one_, Prev: igraph_get_shortest_path --- Shortest path from one vertex to another one_, Up: Shortest Path Related Functions
13.2.7 igraph_get_shortest_paths_dijkstra -- Calculates the weighted shortest paths from/to one vertex.
-------------------------------------------------------------------------------------------------------
int igraph_get_shortest_paths_dijkstra(const igraph_t *graph,
igraph_vector_ptr_t *vertices,
igraph_vector_ptr_t *edges,
igraph_integer_t from,
igraph_vs_t to,
const igraph_vector_t *weights,
igraph_neimode_t mode,
igraph_vector_long_t *predecessors,
igraph_vector_long_t *inbound_edges);
If there is more than one path with the smallest weight between two
vertices, this function gives only one of them.
*Arguments:. *
`graph':
The graph object.
`vertices':
The result, the ids of the vertices along the paths. This is a
pointer vector, each element points to a vector object. These
should be initialized before passing them to the function, which
will properly clear and/or resize them and fill the ids of the
vertices along the geodesics from/to the vertices. Supply a null
pointer here if you don't need these vectors. Normally, either
this argument, or the `edges' should be non-null, but no error or
warning is given if they are both null pointers.
`edges':
The result, the ids of the edges along the paths. This is a
pointer vector, each element points to a vector object. These
should be initialized before passing them to the function, which
will properly clear and/or resize them and fill the ids of the
vertices along the geodesics from/to the vertices. Supply a null
pointer here if you don't need these vectors. Normally, either
this argument, or the `vertices' should be non-null, but no error
or warning is given if they are both null pointers.
`from':
The id of the vertex from/to which the geodesics are calculated.
`to':
Vertex sequence with the ids of the vertices to/from which the
shortest paths will be calculated. A vertex might be given multiple
times.
`weights':
a vector holding the edge weights. All weights must be positive.
`mode':
The type of shortest paths to be use for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the outgoing paths are calculated.
`IGRAPH_IN '
the incoming paths are calculated.
`IGRAPH_ALL '
the directed graph is considered as an undirected one for the
computation.
`predecessors':
A pointer to an initialized igraph vector or null. If not null, a
vector containing the predecessor of each vertex in the single
source shortest path tree is returned here. The predecessor of
vertex i in the tree is the vertex from which vertex i was
reached. The predecessor of the start vertex (in the `from'
argument) is itself by definition. If the predecessor is -1, it
means that the given vertex was not reached from the source during
the search. Note that the search terminates if all the vertices in
`to' are reached.
`inbound_edges':
A pointer to an initialized igraph vector or null. If not null, a
vector containing the inbound edge of each vertex in the single
source shortest path tree is returned here. The inbound edge of
vertex i in the tree is the edge via which vertex i was reached.
The start vertex and vertices that were not reached during the
search will have -1 in the corresponding entry of the vector. Note
that the search terminates if all the vertices in `to' are reached.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID'
`from' is invalid vertex id, or the length of `to' is not the
same as the length of `res'.
`IGRAPH_EINVMODE '
invalid mode argument.
Time complexity: O(|E|log|E|+|V|), where |V| is the number of
vertices and |E| is the number of edges
*See also:. *
`'
`igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) if you only need the path length but not the
paths themselves, `igraph_get_shortest_paths()' (*note
igraph_get_shortest_paths --- Calculates the shortest paths
from/to one vertex_::) if all edge weights are equal.
* File examples/simple/igraph_get_shortest_paths_dijkstra.c*
File: igraph_reference_manual.info, Node: igraph_get_shortest_path_dijkstra --- Weighted shortest path from one vertex to another one_, Next: igraph_get_all_shortest_paths --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Prev: igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest paths from/to one vertex_, Up: Shortest Path Related Functions
13.2.8 igraph_get_shortest_path_dijkstra -- Weighted shortest path from one vertex to another one.
--------------------------------------------------------------------------------------------------
int igraph_get_shortest_path_dijkstra(const igraph_t *graph,
igraph_vector_t *vertices,
igraph_vector_t *edges,
igraph_integer_t from,
igraph_integer_t to,
const igraph_vector_t *weights,
igraph_neimode_t mode);
Calculates a single (positively) weighted shortest path from a
single vertex to another one, using Dijkstra's algorithm.
This function is a special case (and a wrapper) to
`igraph_get_shortest_paths_dijkstra()' (*note
igraph_get_shortest_paths_dijkstra --- Calculates the weighted shortest
paths from/to one vertex_::).
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`vertices':
Pointer to an initialized vector or a null pointer. If not a null
pointer, then the vertex ids along the path are stored here,
including the source and target vertices.
`edges':
Pointer to an uninitialized vector or a null pointer. If not a
null pointer, then the edge ids along the path are stored here.
`from':
The id of the source vertex.
`to':
The id of the target vertex.
`weights':
Vector of edge weights, in the order of edge ids. They must be
non-negative, otherwise the algorithm does not work.
`mode':
A constant specifying how edge directions are considered in
directed graphs. `IGRAPH_OUT' follows edge directions, `IGRAPH_IN'
follows the opposite directions, and `IGRAPH_ALL' ignores edge
directions. This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|E|log|E|+|V|), |V| is the number of vertices,
|E| is the number of edges in the graph.
*See also:. *
`'
`igraph_get_shortest_paths_dijkstra()' (*note
igraph_get_shortest_paths_dijkstra --- Calculates the weighted
shortest paths from/to one vertex_::) for the version with more
target vertices.
File: igraph_reference_manual.info, Node: igraph_get_all_shortest_paths --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Next: igraph_get_all_shortest_paths_dijkstra --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Prev: igraph_get_shortest_path_dijkstra --- Weighted shortest path from one vertex to another one_, Up: Shortest Path Related Functions
13.2.9 igraph_get_all_shortest_paths -- Finds all shortest paths (geodesics) from a vertex to all other vertices.
-----------------------------------------------------------------------------------------------------------------
int igraph_get_all_shortest_paths(const igraph_t *graph,
igraph_vector_ptr_t *res,
igraph_vector_t *nrgeo,
igraph_integer_t from, const igraph_vs_t to,
igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph object.
`res':
Pointer to an initialized pointer vector, the result will be
stored here in igraph_vector_t objects. Each vector object
contains the vertices along a shortest path from `from' to another
vertex. The vectors are ordered according to their target vertex:
first the shortest paths to vertex 0, then to vertex 1, etc. No
data is included for unreachable vertices.
`nrgeo':
Pointer to an initialized igraph_vector_t object or NULL. If not
NULL the number of shortest paths from `from' are stored here for
every vertex in the graph. Note that the values will be accurate
only for those vertices that are in the target vertex sequence
(see `to'), since the search terminates as soon as all the target
vertices have been found.
`from':
The id of the vertex from/to which the geodesics are calculated.
`to':
Vertex sequence with the ids of the vertices to/from which the
shortest paths will be calculated. A vertex might be given multiple
times.
`mode':
The type of shortest paths to be use for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the lengths of the outgoing paths are calculated.
`IGRAPH_IN '
the lengths of the incoming paths are calculated.
`IGRAPH_ALL '
the directed graph is considered as an undirected one for the
computation.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID'
`from' is invalid vertex id.
`IGRAPH_EINVMODE '
invalid mode argument.
Added in version 0.2.
Time complexity: O(|V|+|E|) for most graphs, O(|V|^2) in the worst
case.
File: igraph_reference_manual.info, Node: igraph_get_all_shortest_paths_dijkstra --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Next: igraph_average_path_length --- Calculates the average geodesic length in a graph_, Prev: igraph_get_all_shortest_paths --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Up: Shortest Path Related Functions
13.2.10 igraph_get_all_shortest_paths_dijkstra -- Finds all shortest paths (geodesics) from a vertex to all other vertices.
---------------------------------------------------------------------------------------------------------------------------
int igraph_get_all_shortest_paths_dijkstra(const igraph_t *graph,
igraph_vector_ptr_t *res,
igraph_vector_t *nrgeo,
igraph_integer_t from, igraph_vs_t to,
const igraph_vector_t *weights,
igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph object.
`res':
Pointer to an initialized pointer vector, the result will be
stored here in igraph_vector_t objects. Each vector object
contains the vertices along a shortest path from `from' to another
vertex. The vectors are ordered according to their target vertex:
first the shortest paths to vertex 0, then to vertex 1, etc. No
data is included for unreachable vertices.
`nrgeo':
Pointer to an initialized igraph_vector_t object or NULL. If not
NULL the number of shortest paths from `from' are stored here for
every vertex in the graph. Note that the values will be accurate
only for those vertices that are in the target vertex sequence
(see `to'), since the search terminates as soon as all the target
vertices have been found.
`from':
The id of the vertex from/to which the geodesics are calculated.
`to':
Vertex sequence with the ids of the vertices to/from which the
shortest paths will be calculated. A vertex might be given multiple
times.
`weights':
a vector holding the edge weights. All weights must be
non-negative.
`mode':
The type of shortest paths to be use for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the outgoing paths are calculated.
`IGRAPH_IN '
the incoming paths are calculated.
`IGRAPH_ALL '
the directed graph is considered as an undirected one for the
computation.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID'
`from' is invalid vertex id, or the length of `to' is not the
same as the length of `res'.
`IGRAPH_EINVMODE '
invalid mode argument.
Time complexity: O(|E|log|E|+|V|), where |V| is the number of
vertices and |E| is the number of edges
*See also:. *
`'
`igraph_shortest_paths_dijkstra()' (*note
igraph_shortest_paths_dijkstra --- Weighted shortest paths from
some sources_::) if you only need the path length but not the
paths themselves, `igraph_get_all_shortest_paths()' (*note
igraph_get_all_shortest_paths --- Finds all shortest paths
[geodesics] from a vertex to all other vertices_::) if all edge
weights are equal.
* File examples/simple/igraph_get_all_shortest_paths_dijkstra.c*
File: igraph_reference_manual.info, Node: igraph_average_path_length --- Calculates the average geodesic length in a graph_, Next: igraph_path_length_hist --- Create a histogram of all shortest path lengths_, Prev: igraph_get_all_shortest_paths_dijkstra --- Finds all shortest paths [geodesics] from a vertex to all other vertices_, Up: Shortest Path Related Functions
13.2.11 igraph_average_path_length -- Calculates the average geodesic length in a graph.
----------------------------------------------------------------------------------------
int igraph_average_path_length(const igraph_t *graph, igraph_real_t *res,
igraph_bool_t directed, igraph_bool_t unconn);
*Arguments:. *
`graph':
The graph object.
`res':
Pointer to a real number, this will contain the result.
`directed':
Boolean, whether to consider directed paths. Ignored for
undirected graphs.
`unconn':
What to do if the graph is not connected. If `TRUE' the average of
the geodesics within the components will be returned, otherwise
the number of vertices is used for the length of non-existing
geodesics. (The rationale behind this is that this is always
longer than the longest possible geodesic in a graph.)
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for data structures
Time complexity: O(|V||E|), the number of vertices times the number
of edges.
* File examples/simple/igraph_average_path_length.c*
File: igraph_reference_manual.info, Node: igraph_path_length_hist --- Create a histogram of all shortest path lengths_, Next: igraph_diameter --- Calculates the diameter of a graph [longest geodesic]_, Prev: igraph_average_path_length --- Calculates the average geodesic length in a graph_, Up: Shortest Path Related Functions
13.2.12 igraph_path_length_hist -- Create a histogram of all shortest path lengths.
-----------------------------------------------------------------------------------
int igraph_path_length_hist(const igraph_t *graph, igraph_vector_t *res,
igraph_real_t *unconnected, igraph_bool_t directed);
This function calculates a histogram, by calculating the shortest
path length between each pair of vertices. For directed graphs both
directions might be considered and then every pair of vertices appears
twice in the histogram.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized vector, the result is stored here. The
first (i.e. zeroth) element contains the number of shortest paths
of length 1, etc. The supplied vector is resized as needed.
`unconnected':
Pointer to a real number, the number of pairs for which the second
vertex is not reachable from the first is stored here.
`directed':
Whether to consider directed paths in a directed graph (if not
zero). This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|V||E|), the number of vertices times the number
of edges.
*See also:. *
`'
`igraph_average_path_length()' (*note igraph_average_path_length
--- Calculates the average geodesic length in a graph_::) and
`igraph_shortest_paths()' (*note igraph_shortest_paths --- The
length of the shortest paths between vertices_::)
File: igraph_reference_manual.info, Node: igraph_diameter --- Calculates the diameter of a graph [longest geodesic]_, Next: igraph_diameter_dijkstra --- Weighted diameter using Dijkstra's algorithm; non-negative weights only_, Prev: igraph_path_length_hist --- Create a histogram of all shortest path lengths_, Up: Shortest Path Related Functions
13.2.13 igraph_diameter -- Calculates the diameter of a graph (longest geodesic).
---------------------------------------------------------------------------------
int igraph_diameter(const igraph_t *graph, igraph_integer_t *pres,
igraph_integer_t *pfrom, igraph_integer_t *pto,
igraph_vector_t *path,
igraph_bool_t directed, igraph_bool_t unconn);
*Arguments:. *
`graph':
The graph object.
`pres':
Pointer to an integer, if not `NULL' then it will contain the
diameter (the actual distance).
`pfrom':
Pointer to an integer, if not `NULL' it will be set to the source
vertex of the diameter path.
`pto':
Pointer to an integer, if not `NULL' it will be set to the target
vertex of the diameter path.
`path':
Pointer to an initialized vector. If not `NULL' the actual longest
geodesic path will be stored here. The vector will be resized as
needed.
`directed':
Boolean, whether to consider directed paths. Ignored for
undirected graphs.
`unconn':
What to do if the graph is not connected. If `TRUE' the longest
geodesic within a component will be returned, otherwise the number
of vertices is returned. (The rationale behind the latter is that
this is always longer than the longest possible diameter in a
graph.)
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
Time complexity: O(|V||E|), the number of vertices times the number
of edges.
* File examples/simple/igraph_diameter.c*
File: igraph_reference_manual.info, Node: igraph_diameter_dijkstra --- Weighted diameter using Dijkstra's algorithm; non-negative weights only_, Next: igraph_girth --- The girth of a graph is the length of the shortest circle in it_, Prev: igraph_diameter --- Calculates the diameter of a graph [longest geodesic]_, Up: Shortest Path Related Functions
13.2.14 igraph_diameter_dijkstra -- Weighted diameter using Dijkstra's algorithm, non-negative weights only.
------------------------------------------------------------------------------------------------------------
int igraph_diameter_dijkstra(const igraph_t *graph,
const igraph_vector_t *weights,
igraph_real_t *pres,
igraph_integer_t *pfrom,
igraph_integer_t *pto,
igraph_vector_t *path,
igraph_bool_t directed,
igraph_bool_t unconn);
The diameter of a graph is its longest geodesic. I.e. the (weighted)
shortest path is calculated for all pairs of vertices and the longest
one is the diameter.
*Arguments:. *
`graph':
The input graph, can be directed or undirected.
`pres':
Pointer to a real number, if not `NULL' then it will contain the
diameter (the actual distance).
`pfrom':
Pointer to an integer, if not `NULL' it will be set to the source
vertex of the diameter path.
`pto':
Pointer to an integer, if not `NULL' it will be set to the target
vertex of the diameter path.
`path':
Pointer to an initialized vector. If not `NULL' the actual longest
geodesic path will be stored here. The vector will be resized as
needed.
`directed':
Boolean, whether to consider directed paths. Ignored for
undirected graphs.
`unconn':
What to do if the graph is not connected. If `TRUE' the longest
geodesic within a component will be returned, otherwise
`IGRAPH_INFINITY' is returned.
*Returns:. *
`'
Error code.
Time complexity: O(|V||E|*log|E|), |V| is the number of vertices,
|E| is the number of edges.
File: igraph_reference_manual.info, Node: igraph_girth --- The girth of a graph is the length of the shortest circle in it_, Next: igraph_eccentricity --- Eccentricity of some vertices, Prev: igraph_diameter_dijkstra --- Weighted diameter using Dijkstra's algorithm; non-negative weights only_, Up: Shortest Path Related Functions
13.2.15 igraph_girth -- The girth of a graph is the length of the shortest circle in it.
----------------------------------------------------------------------------------------
int igraph_girth(const igraph_t *graph, igraph_integer_t *girth,
igraph_vector_t *circle);
The current implementation works for undirected graphs only,
directed graphs are treated as undirected graphs. Loop edges and
multiple edges are ignored.
If the graph is a forest (ie. acyclic), then zero is returned.
This implementation is based on Alon Itai and Michael Rodeh: Finding
a minimum circuit in a graph _ Proceedings of the ninth annual ACM
symposium on Theory of computing _, 1-10, 1977. The first
implementation of this function was done by Keith Briggs, thanks Keith.
*Arguments:. *
`graph':
The input graph.
`girth':
Pointer to an integer, if not `NULL' then the result will be
stored here.
`circle':
Pointer to an initialized vector, the vertex ids in the shortest
circle will be stored here. If `NULL' then it is ignored.
*Returns:. *
`'
Error code.
Time complexity: O((|V|+|E|)^2), |V| is the number of vertices, |E|
is the number of edges in the general case. If the graph has no circles
at all then the function needs O(|V|+|E|) time to realize this and then
it stops.
* File examples/simple/igraph_girth.c*
File: igraph_reference_manual.info, Node: igraph_eccentricity --- Eccentricity of some vertices, Next: igraph_radius --- Radius of a graph, Prev: igraph_girth --- The girth of a graph is the length of the shortest circle in it_, Up: Shortest Path Related Functions
13.2.16 igraph_eccentricity -- Eccentricity of some vertices
------------------------------------------------------------
int igraph_eccentricity(const igraph_t *graph,
igraph_vector_t *res,
igraph_vs_t vids,
igraph_neimode_t mode);
The eccentricity of a vertex is calculated by measuring the shortest
distance from (or to) the vertex, to (or from) all vertices in the
graph, and taking the maximum.
This implementation ignores vertex pairs that are in different
components. Isolated vertices have eccentricity zero.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`res':
Pointer to an initialized vector, the result is stored here.
`vids':
The vertices for which the eccentricity is calculated.
`mode':
What kind of paths to consider for the calculation: `IGRAPH_OUT',
paths that follow edge directions; `IGRAPH_IN', paths that follow
the opposite directions; and `IGRAPH_ALL', paths that ignore edge
directions. This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(v*(|V|+|E|)), where |V| is the number of
vertices, |E| is the number of edges and v is the number of vertices
for which eccentricity is calculated.
*See also:. *
`'
`igraph_radius()' (*note igraph_radius --- Radius of a graph::).
* File examples/simple/igraph_eccentricity.c*
File: igraph_reference_manual.info, Node: igraph_radius --- Radius of a graph, Prev: igraph_eccentricity --- Eccentricity of some vertices, Up: Shortest Path Related Functions
13.2.17 igraph_radius -- Radius of a graph
------------------------------------------
int igraph_radius(const igraph_t *graph, igraph_real_t *radius,
igraph_neimode_t mode);
The radius of a graph is the defined as the minimum eccentricity of
its vertices, see `igraph_eccentricity()' (*note igraph_eccentricity
--- Eccentricity of some vertices::).
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`radius':
Pointer to a real variable, the result is stored here.
`mode':
What kind of paths to consider for the calculation: `IGRAPH_OUT',
paths that follow edge directions; `IGRAPH_IN', paths that follow
the opposite directions; and `IGRAPH_ALL', paths that ignore edge
directions. This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|V|(|V|+|E|)), where |V| is the number of
vertices and |E| is the number of edges.
*See also:. *
`'
`igraph_eccentricity()' (*note igraph_eccentricity ---
Eccentricity of some vertices::).
* File examples/simple/igraph_radius.c*
File: igraph_reference_manual.info, Node: Neighborhood of a vertex, Next: Graph Components, Prev: Shortest Path Related Functions, Up: Structural Properties of Graphs
13.3 Neighborhood of a vertex
=============================
* Menu:
* igraph_neighborhood_size --- Calculates the size of the neighborhood of a given vertex.: igraph_neighborhood_size --- Calculates the size of the neighborhood of a given vertex_.
* igraph_neighborhood --- Calculate the neighborhood of vertices.: igraph_neighborhood --- Calculate the neighborhood of vertices_.
* igraph_neighborhood_graphs --- Create graphs from the neighborhood(s) of some vertex/vertices.: igraph_neighborhood_graphs --- Create graphs from the neighborhood[s] of some vertex/vertices_.
File: igraph_reference_manual.info, Node: igraph_neighborhood_size --- Calculates the size of the neighborhood of a given vertex_, Next: igraph_neighborhood --- Calculate the neighborhood of vertices_, Up: Neighborhood of a vertex
13.3.1 igraph_neighborhood_size -- Calculates the size of the neighborhood of a given vertex.
---------------------------------------------------------------------------------------------
int igraph_neighborhood_size(const igraph_t *graph, igraph_vector_t *res,
igraph_vs_t vids, igraph_integer_t order,
igraph_neimode_t mode);
The neighborhood of a given order of a vertex includes all vertices
which are closer to the vertex than the order. Ie. order 0 is always
the vertex itself, order 1 is the vertex plus its immediate neighbors,
order 2 is order 1 plus the immediate neighbors of the vertices in
order 1, etc.
This function calculates the size of the neighborhood of the given
order for the given vertices.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized vector, the result will be stored here.
It will be resized as needed.
`vids':
The vertices for which the calculation is performed.
`order':
Integer giving the order of the neighborhood.
`mode':
Specifies how to use the direction of the edges if a directed
graph is analyzed. For `IGRAPH_OUT' only the outgoing edges are
followed, so all vertices reachable from the source vertex in at
most `order' steps are counted. For `IGRAPH_IN' all vertices from
which the source vertex is reachable in at most `order' steps are
counted. `IGRAPH_ALL' ignores the direction of the edges. This
argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_neighborhood()' (*note igraph_neighborhood --- Calculate
the neighborhood of vertices_::) for calculating the actual
neighborhood, `igraph_neighborhood_graphs()' (*note
igraph_neighborhood_graphs --- Create graphs from the
neighborhood[s] of some vertex/vertices_::) for creating separate
graphs from the neighborhoods.
Time complexity: O(n*d*o), where n is the number vertices for which
the calculation is performed, d is the average degree, o is the order.
File: igraph_reference_manual.info, Node: igraph_neighborhood --- Calculate the neighborhood of vertices_, Next: igraph_neighborhood_graphs --- Create graphs from the neighborhood[s] of some vertex/vertices_, Prev: igraph_neighborhood_size --- Calculates the size of the neighborhood of a given vertex_, Up: Neighborhood of a vertex
13.3.2 igraph_neighborhood -- Calculate the neighborhood of vertices.
---------------------------------------------------------------------
int igraph_neighborhood(const igraph_t *graph, igraph_vector_ptr_t *res,
igraph_vs_t vids, igraph_integer_t order,
igraph_neimode_t mode);
The neighborhood of a given order of a vertex includes all vertices
which are closer to the vertex than the order. Ie. order 0 is always
the vertex itself, order 1 is the vertex plus its immediate neighbors,
order 2 is order 1 plus the immediate neighbors of the vertices in
order 1, etc.
This function calculates the vertices within the neighborhood of the
specified vertices.
*Arguments:. *
`graph':
The input graph.
`res':
An initialized pointer vector. Note that the objects (pointers) in
the vector will _not_ be freed, but the pointer vector will be
resized as needed. The result of the calculation will be stored
here in `vector_t' objects.
`vids':
The vertices for which the calculation is performed.
`order':
Integer giving the order of the neighborhood.
`mode':
Specifies how to use the direction of the edges if a directed
graph is analyzed. For `IGRAPH_OUT' only the outgoing edges are
followed, so all vertices reachable from the source vertex in at
most `order' steps are included. For `IGRAPH_IN' all vertices from
which the source vertex is reachable in at most `order' steps are
included. `IGRAPH_ALL' ignores the direction of the edges. This
argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_neighborhood_size()' (*note igraph_neighborhood_size ---
Calculates the size of the neighborhood of a given vertex_::) to
calculate the size of the neighborhood,
`igraph_neighborhood_graphs()' (*note igraph_neighborhood_graphs
--- Create graphs from the neighborhood[s] of some
vertex/vertices_::) for creating graphs from the neighborhoods.
Time complexity: O(n*d*o), n is the number of vertices for which the
calculation is performed, d is the average degree, o is the order.
File: igraph_reference_manual.info, Node: igraph_neighborhood_graphs --- Create graphs from the neighborhood[s] of some vertex/vertices_, Prev: igraph_neighborhood --- Calculate the neighborhood of vertices_, Up: Neighborhood of a vertex
13.3.3 igraph_neighborhood_graphs -- Create graphs from the neighborhood(s) of some vertex/vertices.
----------------------------------------------------------------------------------------------------
int igraph_neighborhood_graphs(const igraph_t *graph, igraph_vector_ptr_t *res,
igraph_vs_t vids, igraph_integer_t order,
igraph_neimode_t mode);
The neighborhood of a given order of a vertex includes all vertices
which are closer to the vertex than the order. Ie. order 0 is always
the vertex itself, order 1 is the vertex plus its immediate neighbors,
order 2 is order 1 plus the immediate neighbors of the vertices in
order 1, etc.
This function finds every vertex in the neighborhood of a given
parameter vertex and creates a graph from these vertices.
The first version of this function was written by Vincent Matossian,
thanks Vincent.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_t' objects. It will be
resized if needed but note that the objects in the pointer vector
will not be freed.
`vids':
The vertices for which the calculation is performed.
`order':
Integer giving the order of the neighborhood.
`mode':
Specifies how to use the direction of the edges if a directed
graph is analyzed. For `IGRAPH_OUT' only the outgoing edges are
followed, so all vertices reachable from the source vertex in at
most `order' steps are counted. For `IGRAPH_IN' all vertices from
which the source vertex is reachable in at most `order' steps are
counted. `IGRAPH_ALL' ignores the direction of the edges. This
argument is ignored for undirected graphs.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_neighborhood_size()' (*note igraph_neighborhood_size ---
Calculates the size of the neighborhood of a given vertex_::) for
calculating the neighborhood sizes only, `igraph_neighborhood()'
(*note igraph_neighborhood --- Calculate the neighborhood of
vertices_::) for calculating the neighborhoods (but not creating
graphs).
Time complexity: O(n*(|V|+|E|)), where n is the number vertices for
which the calculation is performed, |V| and |E| are the number of
vertices and edges in the original input graph.
File: igraph_reference_manual.info, Node: Graph Components, Next: Degree Sequences, Prev: Neighborhood of a vertex, Up: Structural Properties of Graphs
13.4 Graph Components
=====================
* Menu:
* igraph_subcomponent --- The vertices in the same component as a given vertex.: igraph_subcomponent --- The vertices in the same component as a given vertex_.
* igraph_induced_subgraph --- Creates a subgraph induced by the specified vertices.: igraph_induced_subgraph --- Creates a subgraph induced by the specified vertices_.
* igraph_subgraph_edges --- Creates a subgraph with the specified edges and their endpoints.: igraph_subgraph_edges --- Creates a subgraph with the specified edges and their endpoints_.
* igraph_subgraph --- Creates a subgraph induced by the specified vertices.: igraph_subgraph --- Creates a subgraph induced by the specified vertices_.
* igraph_clusters --- Calculates the (weakly or strongly) connected components in a graph. : igraph_clusters --- Calculates the [weakly or strongly] connected components in a graph_.
* igraph_is_connected --- Decides whether the graph is (weakly or strongly) connected.: igraph_is_connected --- Decides whether the graph is [weakly or strongly] connected_.
* igraph_decompose --- Decompose a graph into connected components.: igraph_decompose --- Decompose a graph into connected components_.
* igraph_decompose_destroy --- Free the memory allocated by igraph_decompose().: igraph_decompose_destroy --- Free the memory allocated by igraph_decompose[]_.
* igraph_biconnected_components --- Calculate biconnected components::
* igraph_articulation_points --- Find the articulation points in a graph.: igraph_articulation_points --- Find the articulation points in a graph_.
File: igraph_reference_manual.info, Node: igraph_subcomponent --- The vertices in the same component as a given vertex_, Next: igraph_induced_subgraph --- Creates a subgraph induced by the specified vertices_, Up: Graph Components
13.4.1 igraph_subcomponent -- The vertices in the same component as a given vertex.
-----------------------------------------------------------------------------------
int igraph_subcomponent(const igraph_t *graph, igraph_vector_t *res, igraph_real_t vertex,
igraph_neimode_t mode);
*Arguments:. *
`graph':
The graph object.
`res':
The result, vector with the ids of the vertices in the same
component.
`vertex':
The id of the vertex of which the component is searched.
`mode':
Type of the component for directed graphs, possible values:
`IGRAPH_OUT '
the set of vertices reachable _from_ the `vertex',
`IGRAPH_IN'
the set of vertices from which the `vertex' is reachable.
`IGRAPH_ALL '
the graph is considered as an undirected graph. Note that
this is _not_ the same as the union of the previous two.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM '
not enough memory for temporary data.
`IGRAPH_EINVVID '
`vertex' is an invalid vertex id
`IGRAPH_EINVMODE'
invalid mode argument passed.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the graph.
*See also:. *
`'
`igraph_subgraph()' (*note igraph_subgraph --- Creates a subgraph
induced by the specified vertices_::) if you want a graph object
consisting only a given set of vertices and the edges between them.
File: igraph_reference_manual.info, Node: igraph_induced_subgraph --- Creates a subgraph induced by the specified vertices_, Next: igraph_subgraph_edges --- Creates a subgraph with the specified edges and their endpoints_, Prev: igraph_subcomponent --- The vertices in the same component as a given vertex_, Up: Graph Components
13.4.2 igraph_induced_subgraph -- Creates a subgraph induced by the specified vertices.
---------------------------------------------------------------------------------------
int igraph_induced_subgraph(const igraph_t *graph, igraph_t *res,
const igraph_vs_t vids, igraph_subgraph_implementation_t impl);
This function collects the specified vertices and all edges between
them to a new graph. As the vertex ids in a graph always start with
zero, this function very likely needs to reassign ids to the vertices.
*Arguments:. *
`graph':
The graph object.
`res':
The subgraph, another graph object will be stored here, do _not_
initialize this object before calling this function, and call
`igraph_destroy()' (*note igraph_destroy --- Frees the memory
allocated for a graph object_::) on it if you don't need it any
more.
`vids':
A vertex selector describing which vertices to keep.
`impl':
This parameter selects which implementation should we use when
constructing the new graph. Basically there are two possibilities:
`IGRAPH_SUBGRAPH_COPY_AND_DELETE' copies the existing graph and
deletes the vertices that are not needed in the new graph, while
`IGRAPH_SUBGRAPH_CREATE_FROM_SCRATCH' constructs the new graph
from scratch without copying the old one. The latter is more
efficient if you are extracting a relatively small subpart of a
very large graph, while the former is better if you want to
extract a subgraph whose size is comparable to the size of the
whole graph. There is a third possibility: `IGRAPH_SUBGRAPH_AUTO'
will select one of the two methods automatically based on the
ratio of the number of vertices in the new and the old graph.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids'.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the original graph.
*See also:. *
`'
`igraph_delete_vertices()' (*note igraph_delete_vertices ---
Removes vertices [with all their edges] from the graph_::) to
delete the specified set of vertices from a graph, the opposite of
this function.
File: igraph_reference_manual.info, Node: igraph_subgraph_edges --- Creates a subgraph with the specified edges and their endpoints_, Next: igraph_subgraph --- Creates a subgraph induced by the specified vertices_, Prev: igraph_induced_subgraph --- Creates a subgraph induced by the specified vertices_, Up: Graph Components
13.4.3 igraph_subgraph_edges -- Creates a subgraph with the specified edges and their endpoints.
------------------------------------------------------------------------------------------------
int igraph_subgraph_edges(const igraph_t *graph, igraph_t *res,
const igraph_es_t eids, igraph_bool_t delete_vertices);
This function collects the specified edges and their endpoints to a
new graph. As the vertex ids in a graph always start with zero, this
function very likely needs to reassign ids to the vertices.
*Arguments:. *
`graph':
The graph object.
`res':
The subgraph, another graph object will be stored here, do _not_
initialize this object before calling this function, and call
`igraph_destroy()' (*note igraph_destroy --- Frees the memory
allocated for a graph object_::) on it if you don't need it any
more.
`eids':
An edge selector describing which edges to keep.
`delete_vertices':
Whether to delete the vertices not incident on any of the
specified edges as well. If `FALSE', the number of vertices in the
result graph will always be equal to the number of vertices in the
input graph.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVEID', invalid edge id in `eids'.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the original graph.
*See also:. *
`'
`igraph_delete_edges()' (*note igraph_delete_edges --- Removes
edges from a graph_::) to delete the specified set of edges from a
graph, the opposite of this function.
File: igraph_reference_manual.info, Node: igraph_subgraph --- Creates a subgraph induced by the specified vertices_, Next: igraph_clusters --- Calculates the [weakly or strongly] connected components in a graph_, Prev: igraph_subgraph_edges --- Creates a subgraph with the specified edges and their endpoints_, Up: Graph Components
13.4.4 igraph_subgraph -- Creates a subgraph induced by the specified vertices.
-------------------------------------------------------------------------------
int igraph_subgraph(const igraph_t *graph, igraph_t *res,
const igraph_vs_t vids);
This function is an alias to `igraph_induced_subgraph()' (*note
igraph_induced_subgraph --- Creates a subgraph induced by the specified
vertices_::), it is left here to ensure API compatibility with igraph
versions prior to 0.6.
This function collects the specified vertices and all edges between
them to a new graph. As the vertex ids in a graph always start with
zero, this function very likely needs to reassign ids to the vertices.
*Arguments:. *
`graph':
The graph object.
`res':
The subgraph, another graph object will be stored here, do _not_
initialize this object before calling this function, and call
`igraph_destroy()' (*note igraph_destroy --- Frees the memory
allocated for a graph object_::) on it if you don't need it any
more.
`vids':
A vertex selector describing which vertices to keep.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids'.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the original graph.
*See also:. *
`'
`igraph_delete_vertices()' (*note igraph_delete_vertices ---
Removes vertices [with all their edges] from the graph_::) to
delete the specified set of vertices from a graph, the opposite of
this function.
File: igraph_reference_manual.info, Node: igraph_clusters --- Calculates the [weakly or strongly] connected components in a graph_, Next: igraph_is_connected --- Decides whether the graph is [weakly or strongly] connected_, Prev: igraph_subgraph --- Creates a subgraph induced by the specified vertices_, Up: Graph Components
13.4.5 igraph_clusters -- Calculates the (weakly or strongly) connected components in a graph.
----------------------------------------------------------------------------------------------
int igraph_clusters(const igraph_t *graph, igraph_vector_t *membership,
igraph_vector_t *csize, igraph_integer_t *no,
igraph_connectedness_t mode);
*Arguments:. *
`graph':
The graph object to analyze.
`membership':
First half of the result will be stored here. For every vertex the
id of its component is given. The vector has to be preinitialized
and will be resized. Alternatively this argument can be `NULL', in
which case it is ignored.
`csize':
The second half of the result. For every component it gives its
size, the order is defined by the component ids. The vector has
to be preinitialized and will be resized. Alternatively this
argument can be `NULL', in which case it is ignored.
`no':
Pointer to an integer, if not `NULL' then the number of clusters
will be stored here.
`mode':
For directed graph this specifies whether to calculate weakly or
strongly connected components. Possible values: `IGRAPH_WEAK',
`IGRAPH_STRONG'. This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid mode argument.
Time complexity: O(|V|+|E|), |V| and |E| are the number of vertices
and edges in the graph.
File: igraph_reference_manual.info, Node: igraph_is_connected --- Decides whether the graph is [weakly or strongly] connected_, Next: igraph_decompose --- Decompose a graph into connected components_, Prev: igraph_clusters --- Calculates the [weakly or strongly] connected components in a graph_, Up: Graph Components
13.4.6 igraph_is_connected -- Decides whether the graph is (weakly or strongly) connected.
------------------------------------------------------------------------------------------
int igraph_is_connected(const igraph_t *graph, igraph_bool_t *res,
igraph_connectedness_t mode);
A graph with zero vertices (i.e. the null graph) is connected by
definition.
*Arguments:. *
`graph':
The graph object to analyze.
`res':
Pointer to a logical variable, the result will be stored here.
`mode':
For a directed graph this specifies whether to calculate weak or
strong connectedness. Possible values: `IGRAPH_WEAK',
`IGRAPH_STRONG'. This argument is ignored for undirected graphs.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': invalid mode argument.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_decompose --- Decompose a graph into connected components_, Next: igraph_decompose_destroy --- Free the memory allocated by igraph_decompose[]_, Prev: igraph_is_connected --- Decides whether the graph is [weakly or strongly] connected_, Up: Graph Components
13.4.7 igraph_decompose -- Decompose a graph into connected components.
-----------------------------------------------------------------------
int igraph_decompose(const igraph_t *graph, igraph_vector_ptr_t *components,
igraph_connectedness_t mode,
long int maxcompno, long int minelements);
Create separate graph for each component of a graph. Note that the
vertex ids in the new graphs will be different than in the original
graph. (Except if there is only one component in the original graph.)
*Arguments:. *
`graph':
The original graph.
`components':
This pointer vector will contain pointers to the subcomponent
graphs. It should be initialized before calling this function and
will be resized to hold the graphs. Don't forget to call
`igraph_destroy()' (*note igraph_destroy --- Frees the memory
allocated for a graph object_::) and free() on the elements of
this pointer vector to free unneeded memory. Alternatively, you can
simply call `igraph_decompose_destroy()' (*note
igraph_decompose_destroy --- Free the memory allocated by
igraph_decompose[]_::) that does this for you.
`mode':
Either `IGRAPH_WEAK' or `IGRAPH_STRONG' for weakly and strongly
connected components respectively. Right now only the former is
implemented.
`maxcompno':
The maximum number of components to return. The first `maxcompno'
components will be returned (which hold at least `minelements'
vertices, see the next parameter), the others will be ignored.
Supply -1 here if you don't want to limit the number of components.
`minelements':
The minimum number of vertices a component should contain in order
to place it in the `components' vector. Eg. supply 2 here to
ignore isolated vertices.
*Returns:. *
`'
Error code, `IGRAPH_ENOMEM' if there is not enough memory to
perform the operation.
Added in version 0.2.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_decompose.c*
File: igraph_reference_manual.info, Node: igraph_decompose_destroy --- Free the memory allocated by igraph_decompose[]_, Next: igraph_biconnected_components --- Calculate biconnected components, Prev: igraph_decompose --- Decompose a graph into connected components_, Up: Graph Components
13.4.8 igraph_decompose_destroy -- Free the memory allocated by `igraph_decompose()'.
-------------------------------------------------------------------------------------
void igraph_decompose_destroy(igraph_vector_ptr_t *complist);
*Arguments:. *
`complist':
The list of graph components, as returned by `igraph_decompose()'
(*note igraph_decompose --- Decompose a graph into connected
components_::).
Time complexity: O(c), c is the number of components.
File: igraph_reference_manual.info, Node: igraph_biconnected_components --- Calculate biconnected components, Next: igraph_articulation_points --- Find the articulation points in a graph_, Prev: igraph_decompose_destroy --- Free the memory allocated by igraph_decompose[]_, Up: Graph Components
13.4.9 igraph_biconnected_components -- Calculate biconnected components
------------------------------------------------------------------------
int igraph_biconnected_components(const igraph_t *graph,
igraph_integer_t *no,
igraph_vector_ptr_t *tree_edges,
igraph_vector_ptr_t *component_edges,
igraph_vector_ptr_t *components,
igraph_vector_t *articulation_points);
A graph is biconnected if the removal of any single vertex (and its
incident edges) does not disconnect it.
A biconnected component of a graph is a maximal biconnected subgraph
of it. The biconnected components of a graph can be given by the
partition of its edges: every edge is a member of exactly one
biconnected component. Note that this is not true for vertices: the
same vertex can be part of many biconnected components.
*Arguments:. *
`graph':
The input graph.
`no':
The number of biconnected components will be stored here.
`tree_edges':
If not a NULL pointer, then the found components are stored here,
in a list of vectors. Every vector in the list is a biconnected
component, represented by its edges. More precisely, a spanning
tree of the biconnected component is returned. Note you'll have to
destroy each vector first by calling `igraph_vector_destroy()'
(*note igraph_vector_destroy --- Destroys a vector object_::) and
then ` free()' on it, plus you need to call
`igraph_vector_ptr_destroy()' (*note igraph_vector_ptr_destroy ---
Destroys a pointer vector_::) on the list to regain all allocated
memory.
`component_edges':
If not a NULL pointer, then the edges of the biconnected
components are stored here, in the same form as for `tree_edges'.
`components':
If not a NULL pointer, then the vertices of the biconnected
components are stored here, in the same format as for the previous
two arguments.
`articulation_points':
If not a NULL pointer, then the articulation points of the graph
are stored in this vector. A vertex is an articulation point if
its removal increases the number of (weakly) connected components
in the graph.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges, but only if you do not calculate `components' and
`component_edges'. If you calculate `components', then it is quadratic
in the number of vertices. If you calculate `component_edges' as well,
then it is cubic in the number of vertices.
*See also:. *
`'
`igraph_articulation_points()' (*note igraph_articulation_points
--- Find the articulation points in a graph_::),
`igraph_clusters()' (*note igraph_clusters --- Calculates the
[weakly or strongly] connected components in a graph_::).
* File examples/simple/igraph_biconnected_components.c*
File: igraph_reference_manual.info, Node: igraph_articulation_points --- Find the articulation points in a graph_, Prev: igraph_biconnected_components --- Calculate biconnected components, Up: Graph Components
13.4.10 igraph_articulation_points -- Find the articulation points in a graph.
------------------------------------------------------------------------------
int igraph_articulation_points(const igraph_t *graph,
igraph_vector_t *res);
A vertex is an articulation point if its removal increases the
number of connected components in the graph.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized vector, the articulation points will be
stored here.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
*See also:. *
`'
`igraph_biconnected_components()' (*note
igraph_biconnected_components --- Calculate biconnected
components::), `igraph_clusters()' (*note igraph_clusters ---
Calculates the [weakly or strongly] connected components in a
graph_::)
File: igraph_reference_manual.info, Node: Degree Sequences, Next: Centrality Measures, Prev: Graph Components, Up: Structural Properties of Graphs
13.5 Degree Sequences
=====================
* Menu:
* igraph_is_degree_sequence --- Determines whether a degree sequence is valid.: igraph_is_degree_sequence --- Determines whether a degree sequence is valid_.
* igraph_is_graphical_degree_sequence --- Determines whether a sequence of integers can be a degree sequence of some::
File: igraph_reference_manual.info, Node: igraph_is_degree_sequence --- Determines whether a degree sequence is valid_, Next: igraph_is_graphical_degree_sequence --- Determines whether a sequence of integers can be a degree sequence of some, Up: Degree Sequences
13.5.1 igraph_is_degree_sequence -- Determines whether a degree sequence is valid.
----------------------------------------------------------------------------------
int igraph_is_degree_sequence(const igraph_vector_t *out_degrees,
const igraph_vector_t *in_degrees, igraph_bool_t *res);
A sequence of n integers is a valid degree sequence if there exists
some graph where the degree of the i-th vertex is equal to the i-th
element of the sequence. Note that the graph may contain multiple or
loop edges; if you are interested in whether the degrees of some
_simple_ graph may realize the given sequence, use
`igraph_is_graphical_degree_sequence' (*note
igraph_is_graphical_degree_sequence --- Determines whether a sequence
of integers can be a degree sequence of some::).
In particular, the function checks whether all the degrees are
non-negative. For undirected graphs, it also checks whether the sum of
degrees is even. For directed graphs, the function checks whether the
lengths of the two degree vectors are equal and whether their sums are
also equal. These are known sufficient and necessary conditions for a
degree sequence to be valid.
*Arguments:. *
`out_degrees':
an integer vector specifying the degree sequence for undirected
graphs or the out-degree sequence for directed graphs.
`in_degrees':
an integer vector specifying the in-degrees of the vertices for
directed graphs. For undirected graphs, this must be null.
`res':
pointer to a boolean variable, the result will be stored here
*Returns:. *
`'
Error code.
Time complexity: O(n), where n is the length of the degree sequence.
File: igraph_reference_manual.info, Node: igraph_is_graphical_degree_sequence --- Determines whether a sequence of integers can be a degree sequence of some, Prev: igraph_is_degree_sequence --- Determines whether a degree sequence is valid_, Up: Degree Sequences
13.5.2 igraph_is_graphical_degree_sequence -- Determines whether a sequence of integers can be a degree sequence of some
------------------------------------------------------------------------------------------------------------------------
int igraph_is_graphical_degree_sequence(const igraph_vector_t *out_degrees,
const igraph_vector_t *in_degrees, igraph_bool_t *res);
simple graph.
References:
Hakimi SL: On the realizability of a set of integers as degrees of
the vertices of a simple graph. J SIAM Appl Math 10:496-506, 1962.
PL Erdos, I Miklos and Z Toroczkai: A simple Havel-Hakimi type
algorithm to realize graphical degree sequences of directed graphs. The
Electronic Journal of Combinatorics 17(1):R66, 2010.
*Arguments:. *
`out_degrees':
an integer vector specifying the degree sequence for undirected
graphs or the out-degree sequence for directed graphs.
`in_degrees':
an integer vector specifying the in-degrees of the vertices for
directed graphs. For undirected graphs, this must be null.
`res':
pointer to a boolean variable, the result will be stored here
*Returns:. *
`'
Error code.
Time complexity: O(n^2 log n) where n is the length of the degree
sequence.
File: igraph_reference_manual.info, Node: Centrality Measures, Next: Estimating Centrality Measures, Prev: Degree Sequences, Up: Structural Properties of Graphs
13.6 Centrality Measures
========================
* Menu:
* igraph_closeness --- Closeness centrality calculations for some vertices.: igraph_closeness --- Closeness centrality calculations for some vertices_.
* igraph_betweenness --- Betweenness centrality of some vertices.: igraph_betweenness --- Betweenness centrality of some vertices_.
* igraph_edge_betweenness --- Betweenness centrality of the edges.: igraph_edge_betweenness --- Betweenness centrality of the edges_.
* igraph_pagerank_algo_t --- PageRank algorithm implementation::
* igraph_pagerank_power_options_t --- Options for the power method::
* igraph_pagerank --- Calculates the Google PageRank for the specified vertices.: igraph_pagerank --- Calculates the Google PageRank for the specified vertices_.
* igraph_pagerank_old --- Calculates the Google PageRank for the specified vertices.: igraph_pagerank_old --- Calculates the Google PageRank for the specified vertices_.
* igraph_personalized_pagerank --- Calculates the personalized Google PageRank for the specified vertices.: igraph_personalized_pagerank --- Calculates the personalized Google PageRank for the specified vertices_.
* igraph_personalized_pagerank_vs --- Calculates the personalized Google PageRank for the specified vertices.: igraph_personalized_pagerank_vs --- Calculates the personalized Google PageRank for the specified vertices_.
* igraph_constraint --- Burt's constraint scores.: igraph_constraint --- Burt's constraint scores_.
* igraph_maxdegree --- Calculate the maximum degree in a graph (or set of vertices).: igraph_maxdegree --- Calculate the maximum degree in a graph [or set of vertices]_.
* igraph_strength --- Strength of the vertices, weighted vertex degree in other words.: igraph_strength --- Strength of the vertices; weighted vertex degree in other words_.
* igraph_eigenvector_centrality --- Eigenvector centrality of the vertices::
* igraph_hub_score --- Kleinberg's hub scores::
* igraph_authority_score --- Kleinerg's authority scores::
File: igraph_reference_manual.info, Node: igraph_closeness --- Closeness centrality calculations for some vertices_, Next: igraph_betweenness --- Betweenness centrality of some vertices_, Up: Centrality Measures
13.6.1 igraph_closeness -- Closeness centrality calculations for some vertices.
-------------------------------------------------------------------------------
int igraph_closeness(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_neimode_t mode,
const igraph_vector_t *weights,
igraph_bool_t normalized);
The closeness centrality of a vertex measures how easily other
vertices can be reached from it (or the other way: how easily it can be
reached from the other vertices). It is defined as the number of the
number of vertices minus one divided by the sum of the lengths of all
geodesics from/to the given vertex.
If the graph is not connected, and there is no path between two
vertices, the number of vertices is used instead the length of the
geodesic. This is always longer than the longest possible geodesic.
*Arguments:. *
`graph':
The graph object.
`res':
The result of the computation, a vector containing the closeness
centrality scores for the given vertices.
`vids':
Vector giving the vertices for which the closeness centrality
scores will be computed.
`mode':
The type of shortest paths to be used for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the lengths of the outgoing paths are calculated.
`IGRAPH_IN '
the lengths of the incoming paths are calculated.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`weights':
An optional vector containing edge weights for weighted closeness.
Supply a null pointer here for traditional, unweighted closeness.
`normalized':
Boolean, whether to normalize results by multiplying by the number
of vertices minus one.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(n|E|), n is the number of vertices for which the
calculation is done and |E| is the number of edges in the graph.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_betweenness()'
(*note igraph_betweenness --- Betweenness centrality of some
vertices_::). See `igraph_closeness_estimate()' (*note
igraph_closeness_estimate --- Closeness centrality estimations for
some vertices_::) to estimate closeness values.
File: igraph_reference_manual.info, Node: igraph_betweenness --- Betweenness centrality of some vertices_, Next: igraph_edge_betweenness --- Betweenness centrality of the edges_, Prev: igraph_closeness --- Closeness centrality calculations for some vertices_, Up: Centrality Measures
13.6.2 igraph_betweenness -- Betweenness centrality of some vertices.
---------------------------------------------------------------------
int igraph_betweenness(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_bool_t directed,
const igraph_vector_t* weights, igraph_bool_t nobigint);
The betweenness centrality of a vertex is the number of geodesics
going through it. If there are more than one geodesic between two
vertices, the value of these geodesics are weighted by one over the
number of geodesics.
*Arguments:. *
`graph':
The graph object.
`res':
The result of the computation, a vector containing the betweenness
scores for the specified vertices.
`vids':
The vertices of which the betweenness centrality scores will be
calculated.
`directed':
Logical, if true directed paths will be considered for directed
graphs. It is ignored for undirected graphs.
`weights':
An optional vector containing edge weights for calculating
weighted betweenness. Supply a null pointer here for unweighted
betweenness.
`nobigint':
Logical, if true, then we don't use big integers for the
calculation, setting this to 1 (=true) should work for most
graphs. It is currently ignored for weighted graphs.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id passed in `vids'.
Time complexity: O(|V||E|), |V| and |E| are the number of vertices
and edges in the graph. Note that the time complexity is independent
of the number of vertices for which the score is calculated.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_closeness()'
(*note igraph_closeness --- Closeness centrality calculations for
some vertices_::). See `igraph_edge_betweenness()' (*note
igraph_edge_betweenness --- Betweenness centrality of the
edges_::) for calculating the betweenness score of the edges in a
graph. See `igraph_betweenness_estimate()' (*note
igraph_betweenness_estimate --- Estimated betweenness centrality
of some vertices_::) to estimate the betweenness score of the
vertices in a graph.
* File examples/simple/igraph_betweenness.c*
File: igraph_reference_manual.info, Node: igraph_edge_betweenness --- Betweenness centrality of the edges_, Next: igraph_pagerank_algo_t --- PageRank algorithm implementation, Prev: igraph_betweenness --- Betweenness centrality of some vertices_, Up: Centrality Measures
13.6.3 igraph_edge_betweenness -- Betweenness centrality of the edges.
----------------------------------------------------------------------
int igraph_edge_betweenness(const igraph_t *graph, igraph_vector_t *result,
igraph_bool_t directed,
const igraph_vector_t *weights);
The betweenness centrality of an edge is the number of geodesics
going through it. If there are more than one geodesics between two
vertices, the value of these geodesics are weighted by one over the
number of geodesics.
*Arguments:. *
`graph':
The graph object.
`result':
The result of the computation, vector containing the betweenness
scores for the edges.
`directed':
Logical, if true directed paths will be considered for directed
graphs. It is ignored for undirected graphs.
`weights':
An optional weight vector for weighted edge betweenness. Supply a
null pointer here for the unweighted version.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
Time complexity: O(|V||E|), |V| and |E| are the number of vertices
and edges in the graph.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_closeness()'
(*note igraph_closeness --- Closeness centrality calculations for
some vertices_::). See `igraph_edge_betweenness()' (*note
igraph_edge_betweenness --- Betweenness centrality of the
edges_::) for calculating the betweenness score of the edges in a
graph. See `igraph_edge_betweenness_estimate()' (*note
igraph_edge_betweenness_estimate --- Estimated betweenness
centrality of the edges_::) to estimate the betweenness score of
the edges in a graph.
* File examples/simple/igraph_edge_betweenness.c*
File: igraph_reference_manual.info, Node: igraph_pagerank_algo_t --- PageRank algorithm implementation, Next: igraph_pagerank_power_options_t --- Options for the power method, Prev: igraph_edge_betweenness --- Betweenness centrality of the edges_, Up: Centrality Measures
13.6.4 igraph_pagerank_algo_t -- PageRank algorithm implementation
------------------------------------------------------------------
typedef enum {
IGRAPH_PAGERANK_ALGO_POWER=0,
IGRAPH_PAGERANK_ALGO_ARPACK=1,
IGRAPH_PAGERANK_ALGO_PRPACK=2
} igraph_pagerank_algo_t;
Algorithms to calculate PageRank.
*Values:. *
`IGRAPH_PAGERANK_ALGO_POWER':
Use a simple power iteration, as it was implemented before igraph
version 0.5.
`IGRAPH_PAGERANK_ALGO_ARPACK':
Use the ARPACK library, this was the PageRank implementation in
igraph from version 0.5, until version 0.7.
`IGRAPH_PAGERANK_ALGO_PRPACK':
Use the PRPACK library. Currently this implementation is
recommended.
File: igraph_reference_manual.info, Node: igraph_pagerank_power_options_t --- Options for the power method, Next: igraph_pagerank --- Calculates the Google PageRank for the specified vertices_, Prev: igraph_pagerank_algo_t --- PageRank algorithm implementation, Up: Centrality Measures
13.6.5 igraph_pagerank_power_options_t -- Options for the power method
----------------------------------------------------------------------
typedef struct igraph_pagerank_power_options_t {
igraph_integer_t niter;
igraph_real_t eps;
} igraph_pagerank_power_options_t;
*Values:. *
`niter':
The number of iterations to perform, integer.
`eps':
The algorithm will consider the calculation as complete if the
difference of values between iterations change less than this
value for every vertex.
File: igraph_reference_manual.info, Node: igraph_pagerank --- Calculates the Google PageRank for the specified vertices_, Next: igraph_pagerank_old --- Calculates the Google PageRank for the specified vertices_, Prev: igraph_pagerank_power_options_t --- Options for the power method, Up: Centrality Measures
13.6.6 igraph_pagerank -- Calculates the Google PageRank for the specified vertices.
------------------------------------------------------------------------------------
int igraph_pagerank(const igraph_t *graph, igraph_pagerank_algo_t algo,
igraph_vector_t *vector,
igraph_real_t *value, const igraph_vs_t vids,
igraph_bool_t directed, igraph_real_t damping,
const igraph_vector_t *weights, void *options);
Starting from version 0.7, igraph has three PageRank implementations,
and the user can choose between them. The first implementation is
`IGRAPH_PAGERANK_ALGO_POWER', also available as the (now deprecated)
function `igraph_pagerank_old()' (*note igraph_pagerank_old ---
Calculates the Google PageRank for the specified vertices_::). The
second implementation is based on the ARPACK library, this was the
default before igraph version 0.7: `IGRAPH_PAGERANK_ALGO_ARPACK'. The
third and recommmended implementation is `IGRAPH_PAGERANK_ALGO_PRPACK'.
This is using the the PRPACK package, see
https://github.com/dgleich/prpack .
Please note that the PageRank of a given vertex depends on the
PageRank of all other vertices, so even if you want to calculate the
PageRank for only some of the vertices, all of them must be calculated.
Requesting the PageRank for only some of the vertices does not result
in any performance increase at all.
For the explanation of the PageRank algorithm, see the following
webpage: http://infolab.stanford.edu/~backrub/google.html
(http://infolab.stanford.edu/~backrub/google.html) , or the following
reference:
Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual
Web Search Engine. Proceedings of the 7th World-Wide Web Conference,
Brisbane, Australia, April 1998.
*Arguments:. *
`graph':
The graph object.
`algo':
The PageRank implementation to use. Possible values:
`IGRAPH_PAGERANK_ALGO_POWER', `IGRAPH_PAGERANK_ALGO_ARPACK',
`IGRAPH_PAGERANK_ALGO_PRPACK'.
`vector':
Pointer to an initialized vector, the result is stored here. It is
resized as needed.
`value':
Pointer to a real variable, the eigenvalue corresponding to the
PageRank vector is stored here. It should be always exactly one.
`vids':
The vertex ids for which the PageRank is returned.
`directed':
Boolean, whether to consider the directedness of the edges. This
is ignored for undirected graphs.
`damping':
The damping factor ("d" in the original paper)
`weights':
Optional edge weights, it is either a null pointer, then the edges
are not weighted, or a vector of the same length as the number of
edges.
`options':
Options to the power method or ARPACK. For the power method,
`IGRAPH_PAGERANK_ALGO_POWER' it must be a pointer to a
`igraph_pagerank_power_options_t' (*note
igraph_pagerank_power_options_t --- Options for the power
method::) object. For `IGRAPH_PAGERANK_ALGO_ARPACK' it must be a
pointer to an `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) object. See
`igraph_arpack_options_t' (*note igraph_arpack_options_t ---
Options for ARPACK::) for details. Note that the function
overwrites the ` n' (number of vertices), ` nev' (1), ` ncv'
(3) and ` which' (LM) parameters and it always starts the
calculation from a non-random vector calculated based on the
degree of the vertices.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids'.
Time complexity: depends on the input graph, usually it is O(|E|),
the number of edges.
*See also:. *
`'
`igraph_pagerank_old()' (*note igraph_pagerank_old --- Calculates
the Google PageRank for the specified vertices_::) for the old
implementation, `igraph_personalized_pagerank()' (*note
igraph_personalized_pagerank --- Calculates the personalized
Google PageRank for the specified vertices_::) and
`igraph_personalized_pagerank_vs()' (*note
igraph_personalized_pagerank_vs --- Calculates the personalized
Google PageRank for the specified vertices_::) for the
personalized PageRank measure, `igraph_arpack_rssolve()' (*note
igraph_arpack_rssolve --- ARPACK solver for symmetric matrices::)
and `igraph_arpack_rnsolve()' (*note igraph_arpack_rnsolve ---
ARPACK solver for non-symmetric matrices::) for the underlying
machinery.
* File examples/simple/igraph_pagerank.c*
File: igraph_reference_manual.info, Node: igraph_pagerank_old --- Calculates the Google PageRank for the specified vertices_, Next: igraph_personalized_pagerank --- Calculates the personalized Google PageRank for the specified vertices_, Prev: igraph_pagerank --- Calculates the Google PageRank for the specified vertices_, Up: Centrality Measures
13.6.7 igraph_pagerank_old -- Calculates the Google PageRank for the specified vertices.
----------------------------------------------------------------------------------------
int igraph_pagerank_old(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_bool_t directed,
igraph_integer_t niter, igraph_real_t eps,
igraph_real_t damping, igraph_bool_t old);
This is an old implementation, it is provided for compatibility with
igraph versions earlier than 0.5. Please use the new implementation
`igraph_pagerank()' (*note igraph_pagerank --- Calculates the Google
PageRank for the specified vertices_::) in new projects.
From version 0.7 this function is deprecated and its use gives a
warning message.
Please note that the PageRank of a given vertex depends on the
PageRank of all other vertices, so even if you want to calculate the
PageRank for only some of the vertices, all of them must be calculated.
Requesting the PageRank for only some of the vertices does not result
in any performance increase at all.
Since the calculation is an iterative process, the algorithm is
stopped after a given count of iterations or if the PageRank value
differences between iterations are less than a predefined value.
For the explanation of the PageRank algorithm, see the following
webpage: http://infolab.stanford.edu/~backrub/google.html
(http://infolab.stanford.edu/~backrub/google.html) , or the following
reference:
Sergey Brin and Larry Page: The Anatomy of a Large-Scale Hypertextual
Web Search Engine. Proceedings of the 7th World-Wide Web Conference,
Brisbane, Australia, April 1998.
*Arguments:. *
`graph':
The graph object.
`res':
The result vector containing the PageRank values for the given
nodes.
`vids':
Vector with the vertex ids
`directed':
Logical, if true directed paths will be considered for directed
graphs. It is ignored for undirected graphs.
`niter':
The maximum number of iterations to perform
`eps':
The algorithm will consider the calculation as complete if the
difference of PageRank values between iterations change less than
this value for every node
`damping':
The damping factor ("d" in the original paper)
`old':
Boolean, whether to use the pre-igraph 0.5 way to calculate page
rank. Not recommended for new applications, only included for
compatibility. If this is non-zero then the damping factor is not
divided by the number of vertices before adding it to the weighted
page rank scores to calculate the new scores. I.e. the formula in
the original PageRank paper is used. Furthermore, if this is
non-zero then the PageRank vector is renormalized after each
iteration.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids'.
Time complexity: O(|V|+|E|) per iteration. A handful iterations
should be enough. Note that if the old-style dumping is used then the
iteration might not converge at all.
*See also:. *
`'
`igraph_pagerank()' (*note igraph_pagerank --- Calculates the
Google PageRank for the specified vertices_::) for the new
implementation.
File: igraph_reference_manual.info, Node: igraph_personalized_pagerank --- Calculates the personalized Google PageRank for the specified vertices_, Next: igraph_personalized_pagerank_vs --- Calculates the personalized Google PageRank for the specified vertices_, Prev: igraph_pagerank_old --- Calculates the Google PageRank for the specified vertices_, Up: Centrality Measures
13.6.8 igraph_personalized_pagerank -- Calculates the personalized Google PageRank for the specified vertices.
--------------------------------------------------------------------------------------------------------------
int igraph_personalized_pagerank(const igraph_t *graph,
igraph_pagerank_algo_t algo, igraph_vector_t *vector,
igraph_real_t *value, const igraph_vs_t vids,
igraph_bool_t directed, igraph_real_t damping,
igraph_vector_t *reset,
const igraph_vector_t *weights,
void *options);
The personalized PageRank is similar to the original PageRank
measure, but the random walk is reset in every step with probability
1-damping to a non-uniform distribution (instead of the uniform
distribution in the original PageRank measure.
Please note that the personalized PageRank of a given vertex depends
on the personalized PageRank of all other vertices, so even if you want
to calculate the personalized PageRank for only some of the vertices,
all of them must be calculated. Requesting the personalized PageRank
for only some of the vertices does not result in any performance
increase at all.
*Arguments:. *
`graph':
The graph object.
`algo':
The PageRank implementation to use. Possible values:
`IGRAPH_PAGERANK_ALGO_POWER', `IGRAPH_PAGERANK_ALGO_ARPACK',
`IGRAPH_PAGERANK_ALGO_PRPACK'.
`vector':
Pointer to an initialized vector, the result is stored here. It is
resized as needed.
`value':
Pointer to a real variable, the eigenvalue corresponding to the
PageRank vector is stored here. It should be always exactly one.
`vids':
The vertex ids for which the PageRank is returned.
`directed':
Boolean, whether to consider the directedness of the edges. This
is ignored for undirected graphs.
`damping':
The damping factor ("d" in the original paper)
`reset':
The probability distribution over the vertices used when resetting
the random walk. It is either a null pointer (denoting a uniform
choice that results in the original PageRank measure) or a vector
of the same length as the number of vertices.
`weights':
Optional edge weights, it is either a null pointer, then the edges
are not weighted, or a vector of the same length as the number of
edges.
`options':
Options to the power method or ARPACK. For the power method,
`IGRAPH_PAGERANK_ALGO_POWER' it must be a pointer to a
`igraph_pagerank_power_options_t' (*note
igraph_pagerank_power_options_t --- Options for the power
method::) object. For `IGRAPH_PAGERANK_ALGO_ARPACK' it must be a
pointer to an `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) object. See
`igraph_arpack_options_t' (*note igraph_arpack_options_t ---
Options for ARPACK::) for details. Note that the function
overwrites the ` n' (number of vertices), ` nev' (1), ` ncv'
(3) and ` which' (LM) parameters and it always starts the
calculation from a non-random vector calculated based on the
degree of the vertices.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids' or an invalid reset
vector in `reset'.
Time complexity: depends on the input graph, usually it is O(|E|),
the number of edges.
*See also:. *
`'
`igraph_pagerank()' (*note igraph_pagerank --- Calculates the
Google PageRank for the specified vertices_::) for the
non-personalized implementation, `igraph_arpack_rssolve()' (*note
igraph_arpack_rssolve --- ARPACK solver for symmetric matrices::)
and `igraph_arpack_rnsolve()' (*note igraph_arpack_rnsolve ---
ARPACK solver for non-symmetric matrices::) for the underlying
machinery.
File: igraph_reference_manual.info, Node: igraph_personalized_pagerank_vs --- Calculates the personalized Google PageRank for the specified vertices_, Next: igraph_constraint --- Burt's constraint scores_, Prev: igraph_personalized_pagerank --- Calculates the personalized Google PageRank for the specified vertices_, Up: Centrality Measures
13.6.9 igraph_personalized_pagerank_vs -- Calculates the personalized Google PageRank for the specified vertices.
-----------------------------------------------------------------------------------------------------------------
int igraph_personalized_pagerank_vs(const igraph_t *graph,
igraph_pagerank_algo_t algo, igraph_vector_t *vector,
igraph_real_t *value, const igraph_vs_t vids,
igraph_bool_t directed, igraph_real_t damping,
igraph_vs_t reset_vids,
const igraph_vector_t *weights,
void *options);
The personalized PageRank is similar to the original PageRank
measure, but the random walk is reset in every step with probability
1-damping to a non-uniform distribution (instead of the uniform
distribution in the original PageRank measure.
This simplified interface takes a vertex sequence and resets the
random walk to one of the vertices in the specified vertex sequence,
chosen uniformly. A typical application of personalized PageRank is
when the random walk is reset to the same vertex every time - this can
easily be achieved using `igraph_vss_1()' (*note igraph_vss_1 ---
Vertex set with a single vertex [immediate version]_::) which generates
a vertex sequence containing only a single vertex.
Please note that the personalized PageRank of a given vertex depends
on the personalized PageRank of all other vertices, so even if you want
to calculate the personalized PageRank for only some of the vertices,
all of them must be calculated. Requesting the personalized PageRank
for only some of the vertices does not result in any performance
increase at all.
*Arguments:. *
`graph':
The graph object.
`algo':
The PageRank implementation to use. Possible values:
`IGRAPH_PAGERANK_ALGO_POWER', `IGRAPH_PAGERANK_ALGO_ARPACK',
`IGRAPH_PAGERANK_ALGO_PRPACK'.
`vector':
Pointer to an initialized vector, the result is stored here. It is
resized as needed.
`value':
Pointer to a real variable, the eigenvalue corresponding to the
PageRank vector is stored here. It should be always exactly one.
`vids':
The vertex ids for which the PageRank is returned.
`directed':
Boolean, whether to consider the directedness of the edges. This
is ignored for undirected graphs.
`damping':
The damping factor ("d" in the original paper)
`reset_vids':
IDs of the vertices used when resetting the random walk.
`weights':
Optional edge weights, it is either a null pointer, then the edges
are not weighted, or a vector of the same length as the number of
edges.
`options':
Options to the power method or ARPACK. For the power method,
`IGRAPH_PAGERANK_ALGO_POWER' it must be a pointer to a
`igraph_pagerank_power_options_t' (*note
igraph_pagerank_power_options_t --- Options for the power
method::) object. For `IGRAPH_PAGERANK_ALGO_ARPACK' it must be a
pointer to an `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) object. See
`igraph_arpack_options_t' (*note igraph_arpack_options_t ---
Options for ARPACK::) for details. Note that the function
overwrites the ` n' (number of vertices), ` nev' (1), ` ncv'
(3) and ` which' (LM) parameters and it always starts the
calculation from a non-random vector calculated based on the
degree of the vertices.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id in `vids' or an empty reset
vertex sequence in `vids_reset'.
Time complexity: depends on the input graph, usually it is O(|E|),
the number of edges.
*See also:. *
`'
`igraph_pagerank()' (*note igraph_pagerank --- Calculates the
Google PageRank for the specified vertices_::) for the
non-personalized implementation, `igraph_arpack_rssolve()' (*note
igraph_arpack_rssolve --- ARPACK solver for symmetric matrices::)
and `igraph_arpack_rnsolve()' (*note igraph_arpack_rnsolve ---
ARPACK solver for non-symmetric matrices::) for the underlying
machinery.
File: igraph_reference_manual.info, Node: igraph_constraint --- Burt's constraint scores_, Next: igraph_maxdegree --- Calculate the maximum degree in a graph [or set of vertices]_, Prev: igraph_personalized_pagerank_vs --- Calculates the personalized Google PageRank for the specified vertices_, Up: Centrality Measures
13.6.10 igraph_constraint -- Burt's constraint scores.
------------------------------------------------------
int igraph_constraint(const igraph_t *graph, igraph_vector_t *res,
igraph_vs_t vids, const igraph_vector_t *weights);
This function calculates Burt's constraint scores for the given
vertices, also known as structural holes.
Burt's constraint is higher if ego has less, or mutually stronger
related (i.e. more redundant) contacts. Burt's measure of constraint,
C[i], of vertex i's ego network V[i], is defined for directed and
valued graphs,
C[i] = sum( sum( (p[i,q] p[q,j])^2, q in V[i], q != i,j ), j in
V[], j != i)
for a graph of order (ie. number of vertices) N, where proportional tie
strengths are defined as
p[i,j]=(a[i,j]+a[j,i]) / sum(a[i,k]+a[k,i], k in V[i], k != i),
a[i,j] are elements of A and the latter being the graph adjacency
matrix. For isolated vertices, constraint is undefined.
Burt, R.S. (2004). Structural holes and good ideas. American Journal
of Sociology 110, 349-399.
The first R version of this function was contributed by Jeroen
Bruggeman.
*Arguments:. *
`graph':
A graph object.
`res':
Pointer to an initialized vector, the result will be stored here.
The vector will be resized to have the appropriate size for
holding the result.
`vids':
Vertex selector containing the vertices for which the constraint
should be calculated.
`weights':
Vector giving the weights of the edges. If it is `NULL' then each
edge is supposed to have the same weight.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+E|+n*d^2), n is the number of vertices for
which the constraint is calculated and d is the average degree, |V| is
the number of vertices, |E| the number of edges in the graph. If the
weights argument is `NULL' then the time complexity is O(|V|+n*d^2).
File: igraph_reference_manual.info, Node: igraph_maxdegree --- Calculate the maximum degree in a graph [or set of vertices]_, Next: igraph_strength --- Strength of the vertices; weighted vertex degree in other words_, Prev: igraph_constraint --- Burt's constraint scores_, Up: Centrality Measures
13.6.11 igraph_maxdegree -- Calculate the maximum degree in a graph (or set of vertices).
-----------------------------------------------------------------------------------------
int igraph_maxdegree(const igraph_t *graph, igraph_integer_t *res,
igraph_vs_t vids, igraph_neimode_t mode,
igraph_bool_t loops);
The largest in-, out- or total degree of the specified vertices is
calculated.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an integer (`igraph_integer_t'), the result will be
stored here.
`vids':
Vector giving the vertex IDs for which the maximum degree will be
calculated.
`mode':
Defines the type of the degree. `IGRAPH_OUT', out-degree,
`IGRAPH_IN', in-degree, `IGRAPH_ALL', total degree (sum of the in-
and out-degree). This parameter is ignored for undirected graphs.
`loops':
Boolean, gives whether the self-loops should be counted.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
`IGRAPH_EINVMODE': invalid mode argument.
Time complexity: O(v) if loops is TRUE, and O(v*d) otherwise. v is
the number vertices for which the degree will be calculated, and d is
their (average) degree.
File: igraph_reference_manual.info, Node: igraph_strength --- Strength of the vertices; weighted vertex degree in other words_, Next: igraph_eigenvector_centrality --- Eigenvector centrality of the vertices, Prev: igraph_maxdegree --- Calculate the maximum degree in a graph [or set of vertices]_, Up: Centrality Measures
13.6.12 igraph_strength -- Strength of the vertices, weighted vertex degree in other words.
-------------------------------------------------------------------------------------------
int igraph_strength(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_neimode_t mode,
igraph_bool_t loops, const igraph_vector_t *weights);
In a weighted network the strength of a vertex is the sum of the
weights of all incident edges. In a non-weighted network this is
exactly the vertex degree.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized vector, the result is stored here. It
will be resized as needed.
`vids':
The vertices for which the calculation is performed.
`mode':
Gives whether to count only outgoing (`IGRAPH_OUT'), incoming
(`IGRAPH_IN') edges or both (`IGRAPH_ALL').
`loops':
A logical scalar, whether to count loop edges as well.
`weights':
A vector giving the edge weights. If this is a NULL pointer, then
`igraph_degree()' (*note igraph_degree --- The degree of some
vertices in a graph_::) is called to perform the calculation.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number vertices and edges.
*See also:. *
`'
`igraph_degree()' (*note igraph_degree --- The degree of some
vertices in a graph_::) for the traditional, non-weighted version.
File: igraph_reference_manual.info, Node: igraph_eigenvector_centrality --- Eigenvector centrality of the vertices, Next: igraph_hub_score --- Kleinberg's hub scores, Prev: igraph_strength --- Strength of the vertices; weighted vertex degree in other words_, Up: Centrality Measures
13.6.13 igraph_eigenvector_centrality -- Eigenvector centrality of the vertices
-------------------------------------------------------------------------------
int igraph_eigenvector_centrality(const igraph_t *graph,
igraph_vector_t *vector,
igraph_real_t *value,
igraph_bool_t directed, igraph_bool_t scale,
const igraph_vector_t *weights,
igraph_arpack_options_t *options);
Eigenvector centrality is a measure of the importance of a node in a
network. It assigns relative scores to all nodes in the network based
on the principle that connections to high-scoring nodes contribute more
to the score of the node in question than equal connections to
low-scoring nodes. In practice, this is determined by calculating the
eigenvector corresponding to the largest positive eigenvalue of the
adjacency matrix. The centrality scores returned by igraph are always
normalized such that the largest eigenvector centrality score is one
(with one exception, see below).
Since the eigenvector centrality scores of nodes in different
components do not affect each other, it may be beneficial for large
graphs to decompose it first into weakly connected components and
calculate the centrality scores individually for each component.
Also note that the adjacency matrix of a directed acyclic graph or
the adjacency matrix of an empty graph does not possess positive
eigenvalues, therefore the eigenvector centrality is not defined for
these graphs. igraph will return an eigenvalue of zero in such cases.
The eigenvector centralities will all be equal for an empty graph and
will all be zeros for a directed acyclic graph. Such pathological cases
can be detected by asking igraph to calculate the eigenvalue as well
(using the `value' parameter, see below) and checking whether the
eigenvalue is very close to zero.
*Arguments:. *
`graph':
The input graph. It might be directed.
`vector':
Pointer to an initialized vector, it will be resized as needed.
The result of the computation is stored here. It can be a null
pointer, then it is ignored.
`value':
If not a null pointer, then the eigenvalue corresponding to the
found eigenvector is stored here.
`directed':
Boolean scalar, whether to consider edge directions in a directed
graph. It is ignored for undirected graphs.
`scale':
If not zero then the result will be scaled such that the absolute
value of the maximum centrality is one.
`weights':
A null pointer (=no edge weights), or a vector giving the weights
of the edges. The algorithm might result complex numbers is some
weights are negative. In this case only the real part is reported.
`options':
Options to ARPACK. See `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) for details.
Note that the function overwrites the ` n' (number of vertices)
parameter and it always starts the calculation from a non-random
vector calculated based on the degree of the vertices.
*Returns:. *
`'
Error code.
Time complexity: depends on the input graph, usually it is
O(|V|+|E|).
*See also:. *
`'
`igraph_pagerank' (*note igraph_pagerank --- Calculates the Google
PageRank for the specified vertices_::) and
`igraph_personalized_pagerank' (*note igraph_personalized_pagerank
--- Calculates the personalized Google PageRank for the specified
vertices_::) for modifications of eigenvector centrality.
* File examples/simple/eigenvector_centrality.c*
File: igraph_reference_manual.info, Node: igraph_hub_score --- Kleinberg's hub scores, Next: igraph_authority_score --- Kleinerg's authority scores, Prev: igraph_eigenvector_centrality --- Eigenvector centrality of the vertices, Up: Centrality Measures
13.6.14 igraph_hub_score -- Kleinberg's hub scores
--------------------------------------------------
int igraph_hub_score(const igraph_t *graph, igraph_vector_t *vector,
igraph_real_t *value, igraph_bool_t scale,
const igraph_vector_t *weights,
igraph_arpack_options_t *options);
The hub scores of the vertices are defined as the principal
eigenvector of ` A*A^T' , where ` A' is the adjacency matrix of the
graph, ` A^T' is its transposed.
See the following reference on the meaning of this score: J.
Kleinberg. Authoritative sources in a hyperlinked environment. _ Proc.
9th ACM-SIAM Symposium on Discrete Algorithms, _ 1998. Extended version
in _ Journal of the ACM _ 46(1999). Also appears as IBM Research Report
RJ 10076, May 1997.
*Arguments:. *
`graph':
The input graph. Can be directed and undirected.
`vector':
Pointer to an initialized vector, the result is stored here. If a
null pointer then it is ignored.
`value':
If not a null pointer then the eigenvalue corresponding to the
calculated eigenvector is stored here.
`scale':
If not zero then the result will be scaled such that the absolute
value of the maximum centrality is one.
`weights':
A null pointer (=no edge weights), or a vector giving the weights
of the edges.
`options':
Options to ARPACK. See `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) for details.
Note that the function overwrites the ` n' (number of vertices)
parameter and it always starts the calculation from a non-random
vector calculated based on the degree of the vertices.
*Returns:. *
`'
Error code.
Time complexity: depends on the input graph, usually it is O(|V|),
the number of vertices.
*See also:. *
`'
`igraph_authority_score()' (*note igraph_authority_score ---
Kleinerg's authority scores::) for the companion measure,
`igraph_pagerank()' (*note igraph_pagerank --- Calculates the
Google PageRank for the specified vertices_::),
`igraph_personalized_pagerank()' (*note
igraph_personalized_pagerank --- Calculates the personalized
Google PageRank for the specified vertices_::),
`igraph_eigenvector_centrality()' (*note
igraph_eigenvector_centrality --- Eigenvector centrality of the
vertices::) for similar measures.
File: igraph_reference_manual.info, Node: igraph_authority_score --- Kleinerg's authority scores, Prev: igraph_hub_score --- Kleinberg's hub scores, Up: Centrality Measures
13.6.15 igraph_authority_score -- Kleinerg's authority scores
-------------------------------------------------------------
int igraph_authority_score(const igraph_t *graph, igraph_vector_t *vector,
igraph_real_t *value, igraph_bool_t scale,
const igraph_vector_t *weights,
igraph_arpack_options_t *options);
The authority scores of the vertices are defined as the principal
eigenvector of ` A^T*A' , where ` A' is the adjacency matrix of the
graph, ` A^T' is its transposed.
See the following reference on the meaning of this score: J.
Kleinberg. Authoritative sources in a hyperlinked environment. _ Proc.
9th ACM-SIAM Symposium on Discrete Algorithms, _ 1998. Extended version
in _ Journal of the ACM _ 46(1999). Also appears as IBM Research Report
RJ 10076, May 1997.
*Arguments:. *
`graph':
The input graph. Can be directed and undirected.
`vector':
Pointer to an initialized vector, the result is stored here. If a
null pointer then it is ignored.
`value':
If not a null pointer then the eigenvalue corresponding to the
calculated eigenvector is stored here.
`scale':
If not zero then the result will be scaled such that the absolute
value of the maximum centrality is one.
`weights':
A null pointer (=no edge weights), or a vector giving the weights
of the edges.
`options':
Options to ARPACK. See `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) for details.
Note that the function overwrites the ` n' (number of vertices)
parameter and it always starts the calculation from a non-random
vector calculated based on the degree of the vertices.
*Returns:. *
`'
Error code.
Time complexity: depends on the input graph, usually it is O(|V|),
the number of vertices.
*See also:. *
`'
`igraph_hub_score()' (*note igraph_hub_score --- Kleinberg's hub
scores::) for the companion measure, `igraph_pagerank()' (*note
igraph_pagerank --- Calculates the Google PageRank for the
specified vertices_::), `igraph_personalized_pagerank()' (*note
igraph_personalized_pagerank --- Calculates the personalized
Google PageRank for the specified vertices_::),
`igraph_eigenvector_centrality()' (*note
igraph_eigenvector_centrality --- Eigenvector centrality of the
vertices::) for similar measures.
File: igraph_reference_manual.info, Node: Estimating Centrality Measures, Next: Centralization, Prev: Centrality Measures, Up: Structural Properties of Graphs
13.7 Estimating Centrality Measures
===================================
* Menu:
* igraph_closeness_estimate --- Closeness centrality estimations for some vertices.: igraph_closeness_estimate --- Closeness centrality estimations for some vertices_.
* igraph_betweenness_estimate --- Estimated betweenness centrality of some vertices.: igraph_betweenness_estimate --- Estimated betweenness centrality of some vertices_.
* igraph_edge_betweenness_estimate --- Estimated betweenness centrality of the edges.: igraph_edge_betweenness_estimate --- Estimated betweenness centrality of the edges_.
File: igraph_reference_manual.info, Node: igraph_closeness_estimate --- Closeness centrality estimations for some vertices_, Next: igraph_betweenness_estimate --- Estimated betweenness centrality of some vertices_, Up: Estimating Centrality Measures
13.7.1 igraph_closeness_estimate -- Closeness centrality estimations for some vertices.
---------------------------------------------------------------------------------------
int igraph_closeness_estimate(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_neimode_t mode,
igraph_real_t cutoff,
const igraph_vector_t *weights,
igraph_bool_t normalized);
The closeness centrality of a vertex measures how easily other
vertices can be reached from it (or the other way: how easily it can be
reached from the other vertices). It is defined as the number of the
number of vertices minus one divided by the sum of the lengths of all
geodesics from/to the given vertex. When estimating closeness
centrality, igraph considers paths having a length less than or equal
to a prescribed cutoff value.
If the graph is not connected, and there is no such path between two
vertices, the number of vertices is used instead the length of the
geodesic. This is always longer than the longest possible geodesic.
Since the estimation considers vertex pairs with a distance greater
than the given value as disconnected, the resulting estimation will
always be lower than the actual closeness centrality.
*Arguments:. *
`graph':
The graph object.
`res':
The result of the computation, a vector containing the closeness
centrality scores for the given vertices.
`vids':
Vector giving the vertices for which the closeness centrality
scores will be computed.
`mode':
The type of shortest paths to be used for the calculation in
directed graphs. Possible values:
`IGRAPH_OUT '
the lengths of the outgoing paths are calculated.
`IGRAPH_IN '
the lengths of the incoming paths are calculated.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`cutoff':
The maximal length of paths that will be considered. If zero or
negative, the exact closeness will be calculated (no upper limit
on path lengths).
`weights':
An optional vector containing edge weights for weighted closeness.
Supply a null pointer here for traditional, unweighted closeness.
`normalized':
Boolean, whether to normalize results by multiplying by the number
of vertices minus one.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(n|E|), n is the number of vertices for which the
calculation is done and |E| is the number of edges in the graph.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_betweenness()'
(*note igraph_betweenness --- Betweenness centrality of some
vertices_::).
File: igraph_reference_manual.info, Node: igraph_betweenness_estimate --- Estimated betweenness centrality of some vertices_, Next: igraph_edge_betweenness_estimate --- Estimated betweenness centrality of the edges_, Prev: igraph_closeness_estimate --- Closeness centrality estimations for some vertices_, Up: Estimating Centrality Measures
13.7.2 igraph_betweenness_estimate -- Estimated betweenness centrality of some vertices.
----------------------------------------------------------------------------------------
int igraph_betweenness_estimate(const igraph_t *graph, igraph_vector_t *res,
const igraph_vs_t vids, igraph_bool_t directed,
igraph_real_t cutoff,
const igraph_vector_t *weights,
igraph_bool_t nobigint);
The betweenness centrality of a vertex is the number of geodesics
going through it. If there are more than one geodesic between two
vertices, the value of these geodesics are weighted by one over the
number of geodesics. When estimating betweenness centrality, igraph
takes into consideration only those paths that are shorter than or
equal to a prescribed length. Note that the estimated centrality will
always be less than the real one.
*Arguments:. *
`graph':
The graph object.
`res':
The result of the computation, a vector containing the estimated
betweenness scores for the specified vertices.
`vids':
The vertices of which the betweenness centrality scores will be
estimated.
`directed':
Logical, if true directed paths will be considered for directed
graphs. It is ignored for undirected graphs.
`cutoff':
The maximal length of paths that will be considered. If zero or
negative, the exact betweenness will be calculated (no upper limit
on path lengths).
`weights':
An optional vector containing edge weights for calculating
weighted betweenness. Supply a null pointer here for unweighted
betweenness.
`nobigint':
Logical, if true, then we don't use big integers for the
calculation, setting this to 1 (=true) should work for most
graphs. It is currently ignored for weighted graphs.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
`IGRAPH_EINVVID', invalid vertex id passed in `vids'.
Time complexity: O(|V||E|), |V| and |E| are the number of vertices
and edges in the graph. Note that the time complexity is independent
of the number of vertices for which the score is calculated.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_closeness()'
(*note igraph_closeness --- Closeness centrality calculations for
some vertices_::). See `igraph_edge_betweenness()' (*note
igraph_edge_betweenness --- Betweenness centrality of the
edges_::) for calculating the betweenness score of the edges in a
graph.
File: igraph_reference_manual.info, Node: igraph_edge_betweenness_estimate --- Estimated betweenness centrality of the edges_, Prev: igraph_betweenness_estimate --- Estimated betweenness centrality of some vertices_, Up: Estimating Centrality Measures
13.7.3 igraph_edge_betweenness_estimate -- Estimated betweenness centrality of the edges.
-----------------------------------------------------------------------------------------
int igraph_edge_betweenness_estimate(const igraph_t *graph, igraph_vector_t *result,
igraph_bool_t directed, igraph_real_t cutoff,
const igraph_vector_t *weights);
The betweenness centrality of an edge is the number of geodesics
going through it. If there are more than one geodesics between two
vertices, the value of these geodesics are weighted by one over the
number of geodesics. When estimating betweenness centrality, igraph
takes into consideration only those paths that are shorter than or
equal to a prescribed length. Note that the estimated centrality will
always be less than the real one.
*Arguments:. *
`graph':
The graph object.
`result':
The result of the computation, vector containing the betweenness
scores for the edges.
`directed':
Logical, if true directed paths will be considered for directed
graphs. It is ignored for undirected graphs.
`cutoff':
The maximal length of paths that will be considered. If zero or
negative, the exact betweenness will be calculated (no upper limit
on path lengths).
`weights':
An optional weight vector for weighted betweenness. Supply a null
pointer here for unweighted betweenness.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
Time complexity: O(|V||E|), |V| and |E| are the number of vertices
and edges in the graph.
*See also:. *
`'
Other centrality types: `igraph_degree()' (*note igraph_degree ---
The degree of some vertices in a graph_::), `igraph_closeness()'
(*note igraph_closeness --- Closeness centrality calculations for
some vertices_::). See `igraph_betweenness()' (*note
igraph_betweenness --- Betweenness centrality of some vertices_::)
for calculating the betweenness score of the vertices in a graph.
File: igraph_reference_manual.info, Node: Centralization, Next: Similarity Measures, Prev: Estimating Centrality Measures, Up: Structural Properties of Graphs
13.8 Centralization
===================
* Menu:
* igraph_centralization --- Calculate the centralization score from the node level scores::
* igraph_centralization_degree --- Calculate vertex degree and graph centralization::
* igraph_centralization_betweenness --- Calculate vertex betweenness and graph centralization::
* igraph_centralization_closeness --- Calculate vertex closeness and graph centralization::
* igraph_centralization_eigenvector_centrality --- Calculate eigenvector centrality scores and graph centralization::
* igraph_centralization_degree_tmax --- Theoretical maximum for graph centralization based on degree::
* igraph_centralization_betweenness_tmax --- Theoretical maximum for graph centralization based on betweenness::
* igraph_centralization_closeness_tmax --- Theoretical maximum for graph centralization based on closeness::
* igraph_centralization_eigenvector_centrality_tmax --- Theoretical maximum centralization for eigenvector centrality::
File: igraph_reference_manual.info, Node: igraph_centralization --- Calculate the centralization score from the node level scores, Next: igraph_centralization_degree --- Calculate vertex degree and graph centralization, Up: Centralization
13.8.1 igraph_centralization -- Calculate the centralization score from the node level scores
---------------------------------------------------------------------------------------------
igraph_real_t igraph_centralization(const igraph_vector_t *scores,
igraph_real_t theoretical_max,
igraph_bool_t normalized);
For a centrality score defined on the vertices of a graph, it is
possible to define a graph level centralization index, by calculating
the sum of the deviation from the maximum centrality score.
Consequently, the higher the centralization index of the graph, the
more centralized the structure is.
In order to make graphs of different sizes comparable, the
centralization index is usually normalized to a number between zero and
one, by dividing the (unnormalized) centralization score of the most
centralized structure with the same number of vertices.
For most centrality indices the most centralized structure is the
star graph, a single center connected to all other nodes in the
network. There are some variation depending on whether the graph is
directed or not, whether loop edges are allowed, etc.
This function simply calculates the graph level index, if the node
level scores and the theoretical maximum are given. It is called by all
the measure-specific centralization functions.
*Arguments:. *
`scores':
A vector containing the node-level centrality scores.
`theoretical_max':
The graph level centrality score of the most centralized graph
with the same number of vertices. Only used if `normalized' set to
true.
`normalized':
Boolean, whether to normalize the centralization by dividing the
supplied theoretical maximum.
*Returns:. *
`'
The graph level index.
*See also:. *
`'
`igraph_centralization_degree()' (*note
igraph_centralization_degree --- Calculate vertex degree and graph
centralization::), `igraph_centralization_betweenness()' (*note
igraph_centralization_betweenness --- Calculate vertex betweenness
and graph centralization::), `igraph_centralization_closeness()'
(*note igraph_centralization_closeness --- Calculate vertex
closeness and graph centralization::), and
`igraph_centralization_eigenvector_centrality()' (*note
igraph_centralization_eigenvector_centrality --- Calculate
eigenvector centrality scores and graph centralization::) for
specific centralization functions.
Time complexity: O(n), the length of the score vector.
* File examples/simple/centralization.c*
File: igraph_reference_manual.info, Node: igraph_centralization_degree --- Calculate vertex degree and graph centralization, Next: igraph_centralization_betweenness --- Calculate vertex betweenness and graph centralization, Prev: igraph_centralization --- Calculate the centralization score from the node level scores, Up: Centralization
13.8.2 igraph_centralization_degree -- Calculate vertex degree and graph centralization
---------------------------------------------------------------------------------------
int igraph_centralization_degree(const igraph_t *graph, igraph_vector_t *res,
igraph_neimode_t mode, igraph_bool_t loops,
igraph_real_t *centralization,
igraph_real_t *theoretical_max,
igraph_bool_t normalized);
This function calculates the degree of the vertices by passing its
arguments to `igraph_degree()' (*note igraph_degree --- The degree of
some vertices in a graph_::); and it calculates the graph level
centralization index based on the results by calling
`igraph_centralization()' (*note igraph_centralization --- Calculate
the centralization score from the node level scores::).
*Arguments:. *
`graph':
The input graph.
`res':
A vector if you need the node-level degree scores, or a null
pointer otherwise.
`mode':
Constant the specifies the type of degree for directed graphs.
Possible values: `IGRAPH_IN', `IGRAPH_OUT' and `IGRAPH_ALL'. This
argument is ignored for undirected graphs.
`loops':
Boolean, whether to consider loop edges when calculating the
degree (and the centralization).
`centralization':
Pointer to a real number, the centralization score is placed here.
`theoretical_max':
Pointer to real number or a null pointer. If not a null pointer,
then the theoretical maximum graph centrality score for a graph
with the same number vertices is stored here.
`normalized':
Boolean, whether to calculate a normalized centralization score.
See `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::)
for how the normalization is done.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::),
`igraph_degree()' (*note igraph_degree --- The degree of some
vertices in a graph_::).
Time complexity: the complexity of `igraph_degree()' (*note
igraph_degree --- The degree of some vertices in a graph_::) plus O(n),
the number of vertices queried, for calculating the centralization
score.
File: igraph_reference_manual.info, Node: igraph_centralization_betweenness --- Calculate vertex betweenness and graph centralization, Next: igraph_centralization_closeness --- Calculate vertex closeness and graph centralization, Prev: igraph_centralization_degree --- Calculate vertex degree and graph centralization, Up: Centralization
13.8.3 igraph_centralization_betweenness -- Calculate vertex betweenness and graph centralization
-------------------------------------------------------------------------------------------------
int igraph_centralization_betweenness(const igraph_t *graph,
igraph_vector_t *res,
igraph_bool_t directed,
igraph_bool_t nobigint,
igraph_real_t *centralization,
igraph_real_t *theoretical_max,
igraph_bool_t normalized);
This function calculates the betweenness centrality of the vertices
by passing its arguments to `igraph_betweenness()' (*note
igraph_betweenness --- Betweenness centrality of some vertices_::); and
it calculates the graph level centralization index based on the results
by calling `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::).
*Arguments:. *
`graph':
The input graph.
`res':
A vector if you need the node-level betweenness scores, or a null
pointer otherwise.
`directed':
Boolean, whether to consider directed paths when calculating
betweenness.
`nobigint':
Logical, if true, then we don't use big integers for the
calculation, setting this to zero (=false) should work for most
graphs. It is currently ignored for weighted graphs.
`centralization':
Pointer to a real number, the centralization score is placed here.
`theoretical_max':
Pointer to real number or a null pointer. If not a null pointer,
then the theoretical maximum graph centrality score for a graph
with the same number vertices is stored here.
`normalized':
Boolean, whether to calculate a normalized centralization score.
See `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::)
for how the normalization is done.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::),
`igraph_betweenness()' (*note igraph_betweenness --- Betweenness
centrality of some vertices_::).
Time complexity: the complexity of `igraph_betweenness()' (*note
igraph_betweenness --- Betweenness centrality of some vertices_::) plus
O(n), the number of vertices queried, for calculating the
centralization score.
File: igraph_reference_manual.info, Node: igraph_centralization_closeness --- Calculate vertex closeness and graph centralization, Next: igraph_centralization_eigenvector_centrality --- Calculate eigenvector centrality scores and graph centralization, Prev: igraph_centralization_betweenness --- Calculate vertex betweenness and graph centralization, Up: Centralization
13.8.4 igraph_centralization_closeness -- Calculate vertex closeness and graph centralization
---------------------------------------------------------------------------------------------
int igraph_centralization_closeness(const igraph_t *graph,
igraph_vector_t *res,
igraph_neimode_t mode,
igraph_real_t *centralization,
igraph_real_t *theoretical_max,
igraph_bool_t normalized);
This function calculates the closeness centrality of the vertices by
passing its arguments to `igraph_closeness()' (*note igraph_closeness
--- Closeness centrality calculations for some vertices_::); and it
calculates the graph level centralization index based on the results by
calling `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::).
*Arguments:. *
`graph':
The input graph.
`res':
A vector if you need the node-level closeness scores, or a null
pointer otherwise.
`mode':
Constant the specifies the type of closeness for directed graphs.
Possible values: `IGRAPH_IN', `IGRAPH_OUT' and `IGRAPH_ALL'. This
argument is ignored for undirected graphs. See
`igraph_closeness()' (*note igraph_closeness --- Closeness
centrality calculations for some vertices_::) argument with the
same name for more.
`centralization':
Pointer to a real number, the centralization score is placed here.
`theoretical_max':
Pointer to real number or a null pointer. If not a null pointer,
then the theoretical maximum graph centrality score for a graph
with the same number vertices is stored here.
`normalized':
Boolean, whether to calculate a normalized centralization score.
See `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::)
for how the normalization is done.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::),
`igraph_closeness()' (*note igraph_closeness --- Closeness
centrality calculations for some vertices_::).
Time complexity: the complexity of `igraph_closeness()' (*note
igraph_closeness --- Closeness centrality calculations for some
vertices_::) plus O(n), the number of vertices queried, for calculating
the centralization score.
File: igraph_reference_manual.info, Node: igraph_centralization_eigenvector_centrality --- Calculate eigenvector centrality scores and graph centralization, Next: igraph_centralization_degree_tmax --- Theoretical maximum for graph centralization based on degree, Prev: igraph_centralization_closeness --- Calculate vertex closeness and graph centralization, Up: Centralization
13.8.5 igraph_centralization_eigenvector_centrality -- Calculate eigenvector centrality scores and graph centralization
-----------------------------------------------------------------------------------------------------------------------
int igraph_centralization_eigenvector_centrality(
const igraph_t *graph,
igraph_vector_t *vector,
igraph_real_t *value,
igraph_bool_t directed,
igraph_bool_t scale,
igraph_arpack_options_t *options,
igraph_real_t *centralization,
igraph_real_t *theoretical_max,
igraph_bool_t normalized);
This function calculates the eigenvector centrality of the vertices
by passing its arguments to `igraph_eigenvector_centrality' (*note
igraph_eigenvector_centrality --- Eigenvector centrality of the
vertices::)); and it calculates the graph level centralization index
based on the results by calling `igraph_centralization()' (*note
igraph_centralization --- Calculate the centralization score from the
node level scores::).
*Arguments:. *
`graph':
The input graph.
`vector':
A vector if you need the node-level eigenvector centrality scores,
or a null pointer otherwise.
`value':
If not a null pointer, then the leading eigenvalue is stored here.
`scale':
If not zero then the result will be scaled, such that the absolute
value of the maximum centrality is one.
`options':
Options to ARPACK. See `igraph_arpack_options_t' (*note
igraph_arpack_options_t --- Options for ARPACK::) for details.
Note that the function overwrites the ` n' (number of vertices)
parameter and it always starts the calculation from a non-random
vector calculated based on the degree of the vertices.
`centralization':
Pointer to a real number, the centralization score is placed here.
`theoretical_max':
Pointer to real number or a null pointer. If not a null pointer,
then the theoretical maximum graph centrality score for a graph
with the same number vertices is stored here.
`normalized':
Boolean, whether to calculate a normalized centralization score.
See `igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::)
for how the normalization is done.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_centralization()' (*note igraph_centralization ---
Calculate the centralization score from the node level scores::),
`igraph_eigenvector_centrality()' (*note
igraph_eigenvector_centrality --- Eigenvector centrality of the
vertices::).
Time complexity: the complexity of `igraph_eigenvector_centrality()'
(*note igraph_eigenvector_centrality --- Eigenvector centrality of the
vertices::) plus O(|V|), the number of vertices for the calculating the
centralization.
File: igraph_reference_manual.info, Node: igraph_centralization_degree_tmax --- Theoretical maximum for graph centralization based on degree, Next: igraph_centralization_betweenness_tmax --- Theoretical maximum for graph centralization based on betweenness, Prev: igraph_centralization_eigenvector_centrality --- Calculate eigenvector centrality scores and graph centralization, Up: Centralization
13.8.6 igraph_centralization_degree_tmax -- Theoretical maximum for graph centralization based on degree
--------------------------------------------------------------------------------------------------------
int igraph_centralization_degree_tmax(const igraph_t *graph,
igraph_integer_t nodes,
igraph_neimode_t mode,
igraph_bool_t loops,
igraph_real_t *res);
This function returns the theoretical maximum graph centrality based
on vertex degree.
There are two ways to call this function, the first is to supply a
graph as the ` graph' argument, and then the number of vertices is
taken from this object, and its directedness is considered as well. The
` nodes' argument is ignored in this case. The ` mode' argument is
also ignored if the supplied graph is undirected.
The other way is to supply a null pointer as the ` graph' argument.
In this case the ` nodes' and ` mode' arguments are considered.
The most centralized structure is the star. More specifically, for
undirected graphs it is the star, for directed graphs it is the in-star
or the out-star.
*Arguments:. *
`graph':
A graph object or a null pointer, see the description above.
`nodes':
The number of nodes. This is ignored if the ` graph' argument is
not a null pointer.
`mode':
Constant, whether the calculation is based on in-degree (`
IGRAPH_IN' ), out-degree (` IGRAPH_OUT' ) or total degree (`
IGRAPH_ALL' ). This is ignored if the ` graph' argument is not a
null pointer and the given graph is undirected.
`loops':
Boolean scalar, whether to consider loop edges in the calculation.
`res':
Pointer to a real variable, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(1).
*See also:. *
`'
`igraph_centralization_degree()' (*note
igraph_centralization_degree --- Calculate vertex degree and graph
centralization::) and `igraph_centralization()' (*note
igraph_centralization --- Calculate the centralization score from
the node level scores::).
File: igraph_reference_manual.info, Node: igraph_centralization_betweenness_tmax --- Theoretical maximum for graph centralization based on betweenness, Next: igraph_centralization_closeness_tmax --- Theoretical maximum for graph centralization based on closeness, Prev: igraph_centralization_degree_tmax --- Theoretical maximum for graph centralization based on degree, Up: Centralization
13.8.7 igraph_centralization_betweenness_tmax -- Theoretical maximum for graph centralization based on betweenness
------------------------------------------------------------------------------------------------------------------
int igraph_centralization_betweenness_tmax(const igraph_t *graph,
igraph_integer_t nodes,
igraph_bool_t directed,
igraph_real_t *res);
This function returns the theoretical maximum graph centrality based
on vertex betweenness.
There are two ways to call this function, the first is to supply a
graph as the ` graph' argument, and then the number of vertices is
taken from this object, and its directedness is considered as well. The
` nodes' argument is ignored in this case. The ` directed' argument
is also ignored if the supplied graph is undirected.
The other way is to supply a null pointer as the ` graph' argument.
In this case the ` nodes' and ` directed' arguments are considered.
The most centralized structure is the star.
*Arguments:. *
`graph':
A graph object or a null pointer, see the description above.
`nodes':
The number of nodes. This is ignored if the ` graph' argument is
not a null pointer.
`directed':
Boolean scalar, whether to use directed paths in the betweenness
calculation. This argument is ignored if ` graph' is not a null
pointer and it is undirected.
`res':
Pointer to a real variable, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(1).
*See also:. *
`'
`igraph_centralization_betweenness()' (*note
igraph_centralization_betweenness --- Calculate vertex betweenness
and graph centralization::) and `igraph_centralization()' (*note
igraph_centralization --- Calculate the centralization score from
the node level scores::).
File: igraph_reference_manual.info, Node: igraph_centralization_closeness_tmax --- Theoretical maximum for graph centralization based on closeness, Next: igraph_centralization_eigenvector_centrality_tmax --- Theoretical maximum centralization for eigenvector centrality, Prev: igraph_centralization_betweenness_tmax --- Theoretical maximum for graph centralization based on betweenness, Up: Centralization
13.8.8 igraph_centralization_closeness_tmax -- Theoretical maximum for graph centralization based on closeness
--------------------------------------------------------------------------------------------------------------
int igraph_centralization_closeness_tmax(const igraph_t *graph,
igraph_integer_t nodes,
igraph_neimode_t mode,
igraph_real_t *res);
This function returns the theoretical maximum graph centrality based
on vertex closeness.
There are two ways to call this function, the first is to supply a
graph as the ` graph' argument, and then the number of vertices is
taken from this object, and its directedness is considered as well. The
` nodes' argument is ignored in this case. The ` mode' argument is
also ignored if the supplied graph is undirected.
The other way is to supply a null pointer as the ` graph' argument.
In this case the ` nodes' and ` mode' arguments are considered.
The most centralized structure is the star.
*Arguments:. *
`graph':
A graph object or a null pointer, see the description above.
`nodes':
The number of nodes. This is ignored if the ` graph' argument is
not a null pointer.
`mode':
Constant, specifies what kinf of distances to consider to
calculate closeness. See the ` mode' argument of
`igraph_closeness()' (*note igraph_closeness --- Closeness
centrality calculations for some vertices_::) for details. This
argument is ignored if ` graph' is not a null pointer and it is
undirected.
`res':
Pointer to a real variable, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(1).
*See also:. *
`'
`igraph_centralization_closeness()' (*note
igraph_centralization_closeness --- Calculate vertex closeness and
graph centralization::) and `igraph_centralization()' (*note
igraph_centralization --- Calculate the centralization score from
the node level scores::).
File: igraph_reference_manual.info, Node: igraph_centralization_eigenvector_centrality_tmax --- Theoretical maximum centralization for eigenvector centrality, Prev: igraph_centralization_closeness_tmax --- Theoretical maximum for graph centralization based on closeness, Up: Centralization
13.8.9 igraph_centralization_eigenvector_centrality_tmax -- Theoretical maximum centralization for eigenvector centrality
-------------------------------------------------------------------------------------------------------------------------
int igraph_centralization_eigenvector_centrality_tmax(
const igraph_t *graph,
igraph_integer_t nodes,
igraph_bool_t directed,
igraph_bool_t scale,
igraph_real_t *res);
This function returns the theoretical maximum graph centrality based
on vertex eigenvector centrality.
There are two ways to call this function, the first is to supply a
graph as the ` graph' argument, and then the number of vertices is
taken from this object, and its directedness is considered as well. The
` nodes' argument is ignored in this case. The ` directed' argument
is also ignored if the supplied graph is undirected.
The other way is to supply a null pointer as the ` graph' argument.
In this case the ` nodes' and ` directed' arguments are considered.
The most centralized directed structure is the in-star. The most
centralized undirected structure is the graph with a single edge.
*Arguments:. *
`graph':
A graph object or a null pointer, see the description above.
`nodes':
The number of nodes. This is ignored if the ` graph' argument is
not a null pointer.
`directed':
Boolean scalar, whether to consider edge directions. This argument
is ignored if ` graph' is not a null pointer and it is undirected.
`scale':
Whether to rescale the node-level centrality scores to have a
maximum of one.
`res':
Pointer to a real variable, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(1).
*See also:. *
`'
`igraph_centralization_closeness()' (*note
igraph_centralization_closeness --- Calculate vertex closeness and
graph centralization::) and `igraph_centralization()' (*note
igraph_centralization --- Calculate the centralization score from
the node level scores::).
File: igraph_reference_manual.info, Node: Similarity Measures, Next: Spanning Trees, Prev: Centralization, Up: Structural Properties of Graphs
13.9 Similarity Measures
========================
* Menu:
* igraph_bibcoupling --- Bibliographic coupling.: igraph_bibcoupling --- Bibliographic coupling_.
* igraph_cocitation --- Cocitation coupling.: igraph_cocitation --- Cocitation coupling_.
* igraph_similarity_jaccard --- Jaccard similarity coefficient for the given vertices.: igraph_similarity_jaccard --- Jaccard similarity coefficient for the given vertices_.
* igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient for given vertex pairs.: igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient for given vertex pairs_.
* igraph_similarity_jaccard_es --- Jaccard similarity coefficient for a given edge selector.: igraph_similarity_jaccard_es --- Jaccard similarity coefficient for a given edge selector_.
* igraph_similarity_dice --- Dice similarity coefficient.: igraph_similarity_dice --- Dice similarity coefficient_.
* igraph_similarity_dice_pairs --- Dice similarity coefficient for given vertex pairs.: igraph_similarity_dice_pairs --- Dice similarity coefficient for given vertex pairs_.
* igraph_similarity_dice_es --- Dice similarity coefficient for a given edge selector.: igraph_similarity_dice_es --- Dice similarity coefficient for a given edge selector_.
* igraph_similarity_inverse_log_weighted --- Vertex similarity based on the inverse logarithm of vertex degrees. : igraph_similarity_inverse_log_weighted --- Vertex similarity based on the inverse logarithm of vertex degrees_.
File: igraph_reference_manual.info, Node: igraph_bibcoupling --- Bibliographic coupling_, Next: igraph_cocitation --- Cocitation coupling_, Up: Similarity Measures
13.9.1 igraph_bibcoupling -- Bibliographic coupling.
----------------------------------------------------
int igraph_bibcoupling(const igraph_t *graph, igraph_matrix_t *res,
const igraph_vs_t vids);
The bibliographic coupling of two vertices is the number of other
vertices they both cite, `igraph_bibcoupling()' (*note
igraph_bibcoupling --- Bibliographic coupling_::) calculates this. The
bibliographic coupling score for each given vertex and all other
vertices in the graph will be calculated.
*Arguments:. *
`graph':
The graph object to analyze.
`res':
Pointer to a matrix, the result of the calculation will be stored
here. The number of its rows is the same as the number of vertex
ids in `vids', the number of columns is the number of vertices in
the graph.
`vids':
The vertex ids of the vertices for which the calculation will be
done.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
Time complexity: O(|V|d^2), |V| is the number of vertices in the
graph, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_cocitation()' (*note igraph_cocitation --- Cocitation
coupling_::)
File: igraph_reference_manual.info, Node: igraph_cocitation --- Cocitation coupling_, Next: igraph_similarity_jaccard --- Jaccard similarity coefficient for the given vertices_, Prev: igraph_bibcoupling --- Bibliographic coupling_, Up: Similarity Measures
13.9.2 igraph_cocitation -- Cocitation coupling.
------------------------------------------------
int igraph_cocitation(const igraph_t *graph, igraph_matrix_t *res,
const igraph_vs_t vids);
Two vertices are cocited if there is another vertex citing both of
them. `igraph_cocitation()' (*note igraph_cocitation --- Cocitation
coupling_::) simply counts how many times two vertices are cocited.
The cocitation score for each given vertex and all other vertices in
the graph will be calculated.
*Arguments:. *
`graph':
The graph object to analyze.
`res':
Pointer to a matrix, the result of the calculation will be stored
here. The number of its rows is the same as the number of vertex
ids in `vids', the number of columns is the number of vertices in
the graph.
`vids':
The vertex ids of the vertices for which the calculation will be
done.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
Time complexity: O(|V|d^2), |V| is the number of vertices in the
graph, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_bibcoupling()' (*note igraph_bibcoupling --- Bibliographic
coupling_::)
* File examples/simple/igraph_cocitation.c*
File: igraph_reference_manual.info, Node: igraph_similarity_jaccard --- Jaccard similarity coefficient for the given vertices_, Next: igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient for given vertex pairs_, Prev: igraph_cocitation --- Cocitation coupling_, Up: Similarity Measures
13.9.3 igraph_similarity_jaccard -- Jaccard similarity coefficient for the given vertices.
------------------------------------------------------------------------------------------
int igraph_similarity_jaccard(const igraph_t *graph, igraph_matrix_t *res,
const igraph_vs_t vids, igraph_neimode_t mode, igraph_bool_t loops);
The Jaccard similarity coefficient of two vertices is the number of
common neighbors divided by the number of vertices that are neighbors
of at least one of the two vertices being considered. This function
calculates the pairwise Jaccard similarities for some (or all) of the
vertices.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a matrix, the result of the calculation will be stored
here. The number of its rows and columns is the same as the number
of vertex ids in `vids'.
`vids':
The vertex ids of the vertices for which the calculation will be
done.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves in the neighbor sets.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(|V|^2 d), |V| is the number of vertices in the
vertex iterator given, d is the (maximum) degree of the vertices in the
graph.
*See also:. *
`'
`igraph_similarity_dice()' (*note igraph_similarity_dice --- Dice
similarity coefficient_::), a measure very similar to the Jaccard
coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient for given vertex pairs_, Next: igraph_similarity_jaccard_es --- Jaccard similarity coefficient for a given edge selector_, Prev: igraph_similarity_jaccard --- Jaccard similarity coefficient for the given vertices_, Up: Similarity Measures
13.9.4 igraph_similarity_jaccard_pairs -- Jaccard similarity coefficient for given vertex pairs.
------------------------------------------------------------------------------------------------
int igraph_similarity_jaccard_pairs(const igraph_t *graph, igraph_vector_t *res,
const igraph_vector_t *pairs, igraph_neimode_t mode, igraph_bool_t loops);
The Jaccard similarity coefficient of two vertices is the number of
common neighbors divided by the number of vertices that are neighbors
of at least one of the two vertices being considered. This function
calculates the pairwise Jaccard similarities for a list of vertex pairs.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a vector, the result of the calculation will be stored
here. The number of elements is the same as the number of pairs in
`pairs'.
`pairs':
A vector that contains the pairs for which the similarity will be
calculated. Each pair is defined by two consecutive elements, i.e.
the first and second element of the vector specifies the first
pair, the third and fourth element specifies the second pair and
so on.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves in the neighbor sets.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(nd), n is the number of pairs in the given
vector, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_similarity_jaccard()' (*note igraph_similarity_jaccard ---
Jaccard similarity coefficient for the given vertices_::) to
calculate the Jaccard similarity between all pairs of a vertex
set, or `igraph_similarity_dice()' (*note igraph_similarity_dice
--- Dice similarity coefficient_::) and
`igraph_similarity_dice_pairs()' (*note
igraph_similarity_dice_pairs --- Dice similarity coefficient for
given vertex pairs_::) for a measure very similar to the Jaccard
coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_jaccard_es --- Jaccard similarity coefficient for a given edge selector_, Next: igraph_similarity_dice --- Dice similarity coefficient_, Prev: igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient for given vertex pairs_, Up: Similarity Measures
13.9.5 igraph_similarity_jaccard_es -- Jaccard similarity coefficient for a given edge selector.
------------------------------------------------------------------------------------------------
int igraph_similarity_jaccard_es(const igraph_t *graph, igraph_vector_t *res,
const igraph_es_t es, igraph_neimode_t mode, igraph_bool_t loops);
The Jaccard similarity coefficient of two vertices is the number of
common neighbors divided by the number of vertices that are neighbors
of at least one of the two vertices being considered. This function
calculates the pairwise Jaccard similarities for the endpoints of edges
in a given edge selector.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a vector, the result of the calculation will be stored
here. The number of elements is the same as the number of edges in
`es'.
`es':
An edge selector that specifies the edges to be included in the
result.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves in the neighbor sets.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(nd), n is the number of edges in the edge
selector, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_similarity_jaccard()' (*note igraph_similarity_jaccard ---
Jaccard similarity coefficient for the given vertices_::) and
`igraph_similarity_jaccard_pairs()' (*note
igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient
for given vertex pairs_::) to calculate the Jaccard similarity
between all pairs of a vertex set or some selected vertex pairs,
or `igraph_similarity_dice()' (*note igraph_similarity_dice ---
Dice similarity coefficient_::), `igraph_similarity_dice_pairs()'
(*note igraph_similarity_dice_pairs --- Dice similarity
coefficient for given vertex pairs_::) and
`igraph_similarity_dice_es()' (*note igraph_similarity_dice_es ---
Dice similarity coefficient for a given edge selector_::) for a
measure very similar to the Jaccard coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_dice --- Dice similarity coefficient_, Next: igraph_similarity_dice_pairs --- Dice similarity coefficient for given vertex pairs_, Prev: igraph_similarity_jaccard_es --- Jaccard similarity coefficient for a given edge selector_, Up: Similarity Measures
13.9.6 igraph_similarity_dice -- Dice similarity coefficient.
-------------------------------------------------------------
int igraph_similarity_dice(const igraph_t *graph, igraph_matrix_t *res,
const igraph_vs_t vids, igraph_neimode_t mode, igraph_bool_t loops);
The Dice similarity coefficient of two vertices is twice the number
of common neighbors divided by the sum of the degrees of the vertices.
This function calculates the pairwise Dice similarities for some (or
all) of the vertices.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a matrix, the result of the calculation will be stored
here. The number of its rows and columns is the same as the number
of vertex ids in `vids'.
`vids':
The vertex ids of the vertices for which the calculation will be
done.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves as their own neighbors.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(|V|^2 d), |V| is the number of vertices in the
vertex iterator given, d is the (maximum) degree of the vertices in the
graph.
*See also:. *
`'
`igraph_similarity_jaccard()' (*note igraph_similarity_jaccard ---
Jaccard similarity coefficient for the given vertices_::), a
measure very similar to the Dice coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_dice_pairs --- Dice similarity coefficient for given vertex pairs_, Next: igraph_similarity_dice_es --- Dice similarity coefficient for a given edge selector_, Prev: igraph_similarity_dice --- Dice similarity coefficient_, Up: Similarity Measures
13.9.7 igraph_similarity_dice_pairs -- Dice similarity coefficient for given vertex pairs.
------------------------------------------------------------------------------------------
int igraph_similarity_dice_pairs(const igraph_t *graph, igraph_vector_t *res,
const igraph_vector_t *pairs, igraph_neimode_t mode, igraph_bool_t loops);
The Dice similarity coefficient of two vertices is twice the number
of common neighbors divided by the sum of the degrees of the vertices.
This function calculates the pairwise Dice similarities for a list of
vertex pairs.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a vector, the result of the calculation will be stored
here. The number of elements is the same as the number of pairs in
`pairs'.
`pairs':
A vector that contains the pairs for which the similarity will be
calculated. Each pair is defined by two consecutive elements, i.e.
the first and second element of the vector specifies the first
pair, the third and fourth element specifies the second pair and
so on.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves as their own neighbors.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(nd), n is the number of pairs in the given
vector, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_similarity_dice()' (*note igraph_similarity_dice --- Dice
similarity coefficient_::) to calculate the Dice similarity
between all pairs of a vertex set, or
`igraph_similarity_jaccard()' (*note igraph_similarity_jaccard ---
Jaccard similarity coefficient for the given vertices_::),
`igraph_similarity_jaccard_pairs()' (*note
igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient
for given vertex pairs_::) and `igraph_similarity_jaccard_es()'
(*note igraph_similarity_jaccard_es --- Jaccard similarity
coefficient for a given edge selector_::) for a measure very
similar to the Dice coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_dice_es --- Dice similarity coefficient for a given edge selector_, Next: igraph_similarity_inverse_log_weighted --- Vertex similarity based on the inverse logarithm of vertex degrees_, Prev: igraph_similarity_dice_pairs --- Dice similarity coefficient for given vertex pairs_, Up: Similarity Measures
13.9.8 igraph_similarity_dice_es -- Dice similarity coefficient for a given edge selector.
------------------------------------------------------------------------------------------
int igraph_similarity_dice_es(const igraph_t *graph, igraph_vector_t *res,
const igraph_es_t es, igraph_neimode_t mode, igraph_bool_t loops);
The Dice similarity coefficient of two vertices is twice the number
of common neighbors divided by the sum of the degrees of the vertices.
This function calculates the pairwise Dice similarities for the
endpoints of edges in a given edge selector.
*Arguments:. *
`graph':
The graph object to analyze
`res':
Pointer to a vector, the result of the calculation will be stored
here. The number of elements is the same as the number of edges in
`es'.
`es':
An edge selector that specifies the edges to be included in the
result.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node.
`IGRAPH_IN'
the incoming edges will be considered for each node.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation.
`loops':
Whether to include the vertices themselves as their own neighbors.
*Returns:. *
`'
Error code:
`IGRAPH_ENOMEM'
not enough memory for temporary data.
`IGRAPH_EINVVID'
invalid vertex id passed.
`IGRAPH_EINVMODE'
invalid mode argument.
Time complexity: O(nd), n is the number of pairs in the given
vector, d is the (maximum) degree of the vertices in the graph.
*See also:. *
`'
`igraph_similarity_dice()' (*note igraph_similarity_dice --- Dice
similarity coefficient_::) and `igraph_similarity_dice_pairs()'
(*note igraph_similarity_dice_pairs --- Dice similarity
coefficient for given vertex pairs_::) to calculate the Dice
similarity between all pairs of a vertex set or some selected
vertex pairs, or `igraph_similarity_jaccard()' (*note
igraph_similarity_jaccard --- Jaccard similarity coefficient for
the given vertices_::), `igraph_similarity_jaccard_pairs()' (*note
igraph_similarity_jaccard_pairs --- Jaccard similarity coefficient
for given vertex pairs_::) and `igraph_similarity_jaccard_es()'
(*note igraph_similarity_jaccard_es --- Jaccard similarity
coefficient for a given edge selector_::) for a measure very
similar to the Dice coefficient
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: igraph_similarity_inverse_log_weighted --- Vertex similarity based on the inverse logarithm of vertex degrees_, Prev: igraph_similarity_dice_es --- Dice similarity coefficient for a given edge selector_, Up: Similarity Measures
13.9.9 igraph_similarity_inverse_log_weighted -- Vertex similarity based on the inverse logarithm of vertex degrees.
--------------------------------------------------------------------------------------------------------------------
int igraph_similarity_inverse_log_weighted(const igraph_t *graph,
igraph_matrix_t *res, const igraph_vs_t vids, igraph_neimode_t mode);
The inverse log-weighted similarity of two vertices is the number of
their common neighbors, weighted by the inverse logarithm of their
degrees. It is based on the assumption that two vertices should be
considered more similar if they share a low-degree common neighbor,
since high-degree common neighbors are more likely to appear even by
pure chance.
Isolated vertices will have zero similarity to any other vertex.
Self-similarities are not calculated.
See the following paper for more details: Lada A. Adamic and Eytan
Adar: Friends and neighbors on the Web. Social Networks, 25(3):211-230,
2003.
*Arguments:. *
`graph':
The graph object to analyze.
`res':
Pointer to a matrix, the result of the calculation will be stored
here. The number of its rows is the same as the number of vertex
ids in `vids', the number of columns is the number of vertices in
the graph.
`vids':
The vertex ids of the vertices for which the calculation will be
done.
`mode':
The type of neighbors to be used for the calculation in directed
graphs. Possible values:
`IGRAPH_OUT'
the outgoing edges will be considered for each node. Nodes
will be weighted according to their in-degree.
`IGRAPH_IN'
the incoming edges will be considered for each node. Nodes
will be weighted according to their out-degree.
`IGRAPH_ALL'
the directed graph is considered as an undirected one for the
computation. Every node is weighted according to its
undirected degree.
*Returns:. *
`'
Error code: `IGRAPH_EINVVID': invalid vertex id.
Time complexity: O(|V|d^2), |V| is the number of vertices in the
graph, d is the (maximum) degree of the vertices in the graph.
* File examples/simple/igraph_similarity.c*
File: igraph_reference_manual.info, Node: Spanning Trees, Next: Transitivity or Clustering Coefficient, Prev: Similarity Measures, Up: Structural Properties of Graphs
13.10 Spanning Trees
====================
* Menu:
* igraph_minimum_spanning_tree --- Calculates one minimum spanning tree of a graph.: igraph_minimum_spanning_tree --- Calculates one minimum spanning tree of a graph_.
* igraph_minimum_spanning_tree_unweighted --- Calculates one minimum spanning tree of an unweighted graph.: igraph_minimum_spanning_tree_unweighted --- Calculates one minimum spanning tree of an unweighted graph_.
* igraph_minimum_spanning_tree_prim --- Calculates one minimum spanning tree of a weighted graph.: igraph_minimum_spanning_tree_prim --- Calculates one minimum spanning tree of a weighted graph_.
File: igraph_reference_manual.info, Node: igraph_minimum_spanning_tree --- Calculates one minimum spanning tree of a graph_, Next: igraph_minimum_spanning_tree_unweighted --- Calculates one minimum spanning tree of an unweighted graph_, Up: Spanning Trees
13.10.1 igraph_minimum_spanning_tree -- Calculates one minimum spanning tree of a graph.
----------------------------------------------------------------------------------------
int igraph_minimum_spanning_tree(const igraph_t* graph,
igraph_vector_t* res, const igraph_vector_t* weights);
If the graph has more minimum spanning trees (this is always the
case, except if it is a forest) this implementation returns only the
same one.
Directed graphs are considered as undirected for this computation.
If the graph is not connected then its minimum spanning forest is
returned. This is the set of the minimum spanning trees of each
component.
*Arguments:. *
`graph':
The graph object.
`res':
An initialized vector, the IDs of the edges that constitute a
spanning tree will be returned here. Use `igraph_subgraph_edges()'
(*note igraph_subgraph_edges --- Creates a subgraph with the
specified edges and their endpoints_::) to extract the spanning
tree as a separate graph object.
`weights':
A vector containing the weights of the edges in the same order as
the simple edge iterator visits them (i.e. in increasing order of
edge IDs).
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
Time complexity: O(|V|+|E|) for the unweighted case, O(|E| log |V|)
for the weighted case. |V| is the number of vertices, |E| the number of
edges in the graph.
*See also:. *
`'
`igraph_minimum_spanning_tree_unweighted()' (*note
igraph_minimum_spanning_tree_unweighted --- Calculates one minimum
spanning tree of an unweighted graph_::) and
`igraph_minimum_spanning_tree_prim()' (*note
igraph_minimum_spanning_tree_prim --- Calculates one minimum
spanning tree of a weighted graph_::) if you only need the tree as
a separate graph object.
* File examples/simple/igraph_minimum_spanning_tree.c*
File: igraph_reference_manual.info, Node: igraph_minimum_spanning_tree_unweighted --- Calculates one minimum spanning tree of an unweighted graph_, Next: igraph_minimum_spanning_tree_prim --- Calculates one minimum spanning tree of a weighted graph_, Prev: igraph_minimum_spanning_tree --- Calculates one minimum spanning tree of a graph_, Up: Spanning Trees
13.10.2 igraph_minimum_spanning_tree_unweighted -- Calculates one minimum spanning tree of an unweighted graph.
---------------------------------------------------------------------------------------------------------------
int igraph_minimum_spanning_tree_unweighted(const igraph_t *graph,
igraph_t *mst);
If the graph has more minimum spanning trees (this is always the
case, except if it is a forest) this implementation returns only the
same one.
Directed graphs are considered as undirected for this computation.
If the graph is not connected then its minimum spanning forest is
returned. This is the set of the minimum spanning trees of each
component.
*Arguments:. *
`graph':
The graph object.
`mst':
The minimum spanning tree, another graph object. Do _not_
initialize this object before passing it to this function, but be
sure to call `igraph_destroy()' (*note igraph_destroy --- Frees
the memory allocated for a graph object_::) on it if you don't
need it any more.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory for temporary data.
Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| the
number of edges in the graph.
*See also:. *
`'
`igraph_minimum_spanning_tree_prim()' (*note
igraph_minimum_spanning_tree_prim --- Calculates one minimum
spanning tree of a weighted graph_::) for weighted graphs,
`igraph_minimum_spanning_tree()' (*note
igraph_minimum_spanning_tree --- Calculates one minimum spanning
tree of a graph_::) if you need the IDs of the edges that
constitute the spanning tree.
File: igraph_reference_manual.info, Node: igraph_minimum_spanning_tree_prim --- Calculates one minimum spanning tree of a weighted graph_, Prev: igraph_minimum_spanning_tree_unweighted --- Calculates one minimum spanning tree of an unweighted graph_, Up: Spanning Trees
13.10.3 igraph_minimum_spanning_tree_prim -- Calculates one minimum spanning tree of a weighted graph.
------------------------------------------------------------------------------------------------------
int igraph_minimum_spanning_tree_prim(const igraph_t *graph, igraph_t *mst,
const igraph_vector_t *weights);
This function uses Prim's method for carrying out the computation,
see Prim, R.C.: Shortest connection networks and some generalizations,
Bell System Technical Journal, Vol. 36, 1957, 1389-1401.
If the graph has more than one minimum spanning tree, the current
implementation returns always the same one.
Directed graphs are considered as undirected for this computation.
If the graph is not connected then its minimum spanning forest is
returned. This is the set of the minimum spanning trees of each
component.
*Arguments:. *
`graph':
The graph object.
`mst':
The result of the computation, a graph object containing the
minimum spanning tree of the graph. Do _not_ initialize this
object before passing it to this function, but be sure to call
`igraph_destroy()' (*note igraph_destroy --- Frees the memory
allocated for a graph object_::) on it if you don't need it any
more.
`weights':
A vector containing the weights of the edges in the same order as
the simple edge iterator visits them (i.e. in increasing order of
edge IDs).
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM', not enough memory. `IGRAPH_EINVAL',
length of weight vector does not match number of edges.
Time complexity: O(|E| log |V|), |V| is the number of vertices, |E|
the number of edges in the graph.
*See also:. *
`'
`igraph_minimum_spanning_tree_unweighted()' (*note
igraph_minimum_spanning_tree_unweighted --- Calculates one minimum
spanning tree of an unweighted graph_::) for unweighted graphs,
`igraph_minimum_spanning_tree()' (*note
igraph_minimum_spanning_tree --- Calculates one minimum spanning
tree of a graph_::) if you need the IDs of the edges that
constitute the spanning tree.
* File examples/simple/igraph_minimum_spanning_tree.c*
File: igraph_reference_manual.info, Node: Transitivity or Clustering Coefficient, Next: Directedness conversion, Prev: Spanning Trees, Up: Structural Properties of Graphs
13.11 Transitivity or Clustering Coefficient
============================================
* Menu:
* igraph_transitivity_undirected --- Calculates the transitivity (clustering coefficient) of a graph.: igraph_transitivity_undirected --- Calculates the transitivity [clustering coefficient] of a graph_.
* igraph_transitivity_local_undirected --- Calculates the local transitivity (clustering coefficient) of a graph.: igraph_transitivity_local_undirected --- Calculates the local transitivity [clustering coefficient] of a graph_.
* igraph_transitivity_avglocal_undirected --- Average local transitivity (clustering coefficient).: igraph_transitivity_avglocal_undirected --- Average local transitivity [clustering coefficient]_.
* igraph_transitivity_barrat --- Weighted transitivity, as defined by A. Barrat.: igraph_transitivity_barrat --- Weighted transitivity; as defined by A_ Barrat_.
File: igraph_reference_manual.info, Node: igraph_transitivity_undirected --- Calculates the transitivity [clustering coefficient] of a graph_, Next: igraph_transitivity_local_undirected --- Calculates the local transitivity [clustering coefficient] of a graph_, Up: Transitivity or Clustering Coefficient
13.11.1 igraph_transitivity_undirected -- Calculates the transitivity (clustering coefficient) of a graph.
----------------------------------------------------------------------------------------------------------
int igraph_transitivity_undirected(const igraph_t *graph,
igraph_real_t *res,
igraph_transitivity_mode_t mode);
The transitivity measures the probability that two neighbors of a
vertex are connected. More precisely, this is the ratio of the
triangles and connected triples in the graph, the result is a single
real number. Directed graphs are considered as undirected ones.
Note that this measure is different from the local transitivity
measure (see `igraph_transitivity_local_undirected()' (*note
igraph_transitivity_local_undirected --- Calculates the local
transitivity [clustering coefficient] of a graph_::) ) as it calculates
a single value for the whole graph. See the following reference for
more details:
S. Wasserman and K. Faust: Social Network Analysis: Methods and
Applications. Cambridge: Cambridge University Press, 1994.
Clustering coefficient is an alternative name for transitivity.
*Arguments:. *
`graph':
The graph object.
`res':
Pointer to a real variable, the result will be stored here.
`mode':
Defines how to treat graphs with no connected triples.
`IGRAPH_TRANSITIVITY_NAN' returns `NaN' in this case,
`IGRAPH_TRANSITIVITY_ZERO' returns zero.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM': not enough memory for temporary data.
*See also:. *
`'
`igraph_transitivity_local_undirected()' (*note
igraph_transitivity_local_undirected --- Calculates the local
transitivity [clustering coefficient] of a graph_::),
`igraph_transitivity_avglocal_undirected()' (*note
igraph_transitivity_avglocal_undirected --- Average local
transitivity [clustering coefficient]_::).
Time complexity: O(|V|*d^2), |V| is the number of vertices in the
graph, d is the average node degree.
* File examples/simple/igraph_transitivity.c*
File: igraph_reference_manual.info, Node: igraph_transitivity_local_undirected --- Calculates the local transitivity [clustering coefficient] of a graph_, Next: igraph_transitivity_avglocal_undirected --- Average local transitivity [clustering coefficient]_, Prev: igraph_transitivity_undirected --- Calculates the transitivity [clustering coefficient] of a graph_, Up: Transitivity or Clustering Coefficient
13.11.2 igraph_transitivity_local_undirected -- Calculates the local transitivity (clustering coefficient) of a graph.
----------------------------------------------------------------------------------------------------------------------
int igraph_transitivity_local_undirected(const igraph_t *graph,
igraph_vector_t *res,
const igraph_vs_t vids,
igraph_transitivity_mode_t mode);
The transitivity measures the probability that two neighbors of a
vertex are connected. In case of the local transitivity, this
probability is calculated separately for each vertex.
Note that this measure is different from the global transitivity
measure (see `igraph_transitivity_undirected()' (*note
igraph_transitivity_undirected --- Calculates the transitivity
[clustering coefficient] of a graph_::) ) as it calculates a
transitivity value for each vertex individually. See the following
reference for more details:
D. J. Watts and S. Strogatz: Collective dynamics of small-world
networks. Nature 393(6684):440-442 (1998).
Clustering coefficient is an alternative name for transitivity.
*Arguments:. *
`graph':
The input graph, it can be directed but direction of the edges
will be ignored.
`res':
Pointer to an initialized vector, the result will be stored here.
It will be resized as needed.
`vids':
Vertex set, the vertices for which the local transitivity will be
calculated.
`mode':
Defines how to treat vertices with degree less than two.
`IGRAPH_TRANSITIVITY_NAN' returns `NaN' for these vertices,
`IGRAPH_TRANSITIVITY_ZERO' returns zero.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_transitivity_undirected()' (*note
igraph_transitivity_undirected --- Calculates the transitivity
[clustering coefficient] of a graph_::),
`igraph_transitivity_avglocal_undirected()' (*note
igraph_transitivity_avglocal_undirected --- Average local
transitivity [clustering coefficient]_::).
Time complexity: O(n*d^2), n is the number of vertices for which the
transitivity is calculated, d is the average vertex degree.
File: igraph_reference_manual.info, Node: igraph_transitivity_avglocal_undirected --- Average local transitivity [clustering coefficient]_, Next: igraph_transitivity_barrat --- Weighted transitivity; as defined by A_ Barrat_, Prev: igraph_transitivity_local_undirected --- Calculates the local transitivity [clustering coefficient] of a graph_, Up: Transitivity or Clustering Coefficient
13.11.3 igraph_transitivity_avglocal_undirected -- Average local transitivity (clustering coefficient).
-------------------------------------------------------------------------------------------------------
int igraph_transitivity_avglocal_undirected(const igraph_t *graph,
igraph_real_t *res,
igraph_transitivity_mode_t mode);
The transitivity measures the probability that two neighbors of a
vertex are connected. In case of the average local transitivity, this
probability is calculated for each vertex and then the average is
taken. Vertices with less than two neighbors require special treatment,
they will either be left out from the calculation or they will be
considered as having zero transitivity, depending on the `mode'
argument.
Note that this measure is different from the global transitivity
measure (see `igraph_transitivity_undirected()' (*note
igraph_transitivity_undirected --- Calculates the transitivity
[clustering coefficient] of a graph_::) ) as it simply takes the
average local transitivity across the whole network. See the following
reference for more details:
D. J. Watts and S. Strogatz: Collective dynamics of small-world
networks. Nature 393(6684):440-442 (1998).
Clustering coefficient is an alternative name for transitivity.
*Arguments:. *
`graph':
The input graph, directed graphs are considered as undirected ones.
`res':
Pointer to a real variable, the result will be stored here.
`mode':
Defines how to treat vertices with degree less than two.
`IGRAPH_TRANSITIVITY_NAN' leaves them out from averaging,
`IGRAPH_TRANSITIVITY_ZERO' includes them with zero transitivity.
The result will be `NaN' if the mode is `IGRAPH_TRANSITIVITY_NAN'
and there are no vertices with more than one neighbor.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_transitivity_undirected()' (*note
igraph_transitivity_undirected --- Calculates the transitivity
[clustering coefficient] of a graph_::),
`igraph_transitivity_local_undirected()' (*note
igraph_transitivity_local_undirected --- Calculates the local
transitivity [clustering coefficient] of a graph_::).
Time complexity: O(|V|*d^2), |V| is the number of vertices in the
graph and d is the average degree.
File: igraph_reference_manual.info, Node: igraph_transitivity_barrat --- Weighted transitivity; as defined by A_ Barrat_, Prev: igraph_transitivity_avglocal_undirected --- Average local transitivity [clustering coefficient]_, Up: Transitivity or Clustering Coefficient
13.11.4 igraph_transitivity_barrat -- Weighted transitivity, as defined by A. Barrat.
-------------------------------------------------------------------------------------
int igraph_transitivity_barrat(const igraph_t *graph,
igraph_vector_t *res,
const igraph_vs_t vids,
const igraph_vector_t *weights,
igraph_transitivity_mode_t mode);
This is a local transitivity, i.e. a vertex-level index. For a given
vertex `i', from all triangles in which it participates we consider the
weight of the edges incident on `i'. The transitivity is the sum of
these weights divided by twice the strength of the vertex (see
`igraph_strength()' (*note igraph_strength --- Strength of the
vertices; weighted vertex degree in other words_::)) and the degree of
the vertex minus one. See Alain Barrat, Marc Barthelemy, Romualdo
Pastor-Satorras, Alessandro Vespignani: The architecture of complex
weighted networks, Proc. Natl. Acad. Sci. USA 101, 3747 (2004) at
http://arxiv.org/abs/cond-mat/0311416
(http://arxiv.org/abs/cond-mat/0311416) for the exact formula.
*Arguments:. *
`graph':
The input graph, edge directions are ignored for directed graphs.
Note that the function does NOT work for non-simple graphs.
`res':
Pointer to an initialized vector, the result will be stored here.
It will be resized as needed.
`vids':
The vertices for which the calculation is performed.
`weights':
Edge weights. If this is a null pointer, then a warning is given
and `igraph_transitivity_local_undirected()' (*note
igraph_transitivity_local_undirected --- Calculates the local
transitivity [clustering coefficient] of a graph_::) is called.
`mode':
Defines how to treat vertices with zero strength.
`IGRAPH_TRANSITIVITY_NAN' says that the transitivity of these
vertices is `NaN', `IGRAPH_TRANSITIVITY_ZERO' says it is zero.
*Returns:. *
`'
Error code.
Time complexity: O(|V|*d^2), |V| is the number of vertices in the
graph, d is the average node degree.
*See also:. *
`'
`igraph_transitivity_undirected()' (*note
igraph_transitivity_undirected --- Calculates the transitivity
[clustering coefficient] of a graph_::),
`igraph_transitivity_local_undirected()' (*note
igraph_transitivity_local_undirected --- Calculates the local
transitivity [clustering coefficient] of a graph_::) and
`igraph_transitivity_avglocal_undirected()' (*note
igraph_transitivity_avglocal_undirected --- Average local
transitivity [clustering coefficient]_::) for other kinds of
(non-weighted) transitivity.
File: igraph_reference_manual.info, Node: Directedness conversion, Next: Spectral properties, Prev: Transitivity or Clustering Coefficient, Up: Structural Properties of Graphs
13.12 Directedness conversion
=============================
* Menu:
* igraph_to_directed --- Convert an undirected graph to a directed one::
* igraph_to_undirected --- Convert a directed graph to an undirected one.: igraph_to_undirected --- Convert a directed graph to an undirected one_.
File: igraph_reference_manual.info, Node: igraph_to_directed --- Convert an undirected graph to a directed one, Next: igraph_to_undirected --- Convert a directed graph to an undirected one_, Up: Directedness conversion
13.12.1 igraph_to_directed -- Convert an undirected graph to a directed one
---------------------------------------------------------------------------
int igraph_to_directed(igraph_t *graph,
igraph_to_directed_t mode);
If the supplied graph is directed, this function does nothing.
*Arguments:. *
`graph':
The graph object to convert.
`mode':
Constant, specifies the details of how exactly the conversion is
done. Possible values: `IGRAPH_TO_DIRECTED_ARBITRARY': the number
of edges in the graph stays the same, an arbitrarily directed edge
is created for each undirected edge; `IGRAPH_TO_DIRECTED_MUTUAL':
two directed edges are created for each undirected edge, one in
each direction.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
File: igraph_reference_manual.info, Node: igraph_to_undirected --- Convert a directed graph to an undirected one_, Prev: igraph_to_directed --- Convert an undirected graph to a directed one, Up: Directedness conversion
13.12.2 igraph_to_undirected -- Convert a directed graph to an undirected one.
------------------------------------------------------------------------------
int igraph_to_undirected(igraph_t *graph,
igraph_to_undirected_t mode,
const igraph_attribute_combination_t *edge_comb);
If the supplied graph is undirected, this function does nothing.
*Arguments:. *
`graph':
The graph object to convert.
`mode':
Constant, specifies the details of how exactly the conversion is
done. Possible values: `IGRAPH_TO_UNDIRECTED_EACH': the number of
edges remains constant, an undirected edge is created for each
directed one, this version might create graphs with multiple edges;
`IGRAPH_TO_UNDIRECTED_COLLAPSE': one undirected edge will be
created for each pair of vertices which are connected with at
least one directed edge, no multiple edges will be created.
`IGRAPH_TO_UNDIRECTED_MUTUAL' creates an undirected edge for each
pair of mutual edges in the directed graph. Non-mutual edges are
lost. This mode might create multiple edges.
`edge_comb':
What to do with the edge attributes. See the igraph manual section
about attributes for details.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
* File examples/simple/igraph_to_undirected.c*
File: igraph_reference_manual.info, Node: Spectral properties, Next: Non-simple graphs; multiple and loop edges, Prev: Directedness conversion, Up: Structural Properties of Graphs
13.13 Spectral properties
=========================
* Menu:
* igraph_laplacian --- Returns the Laplacian matrix of a graph::
File: igraph_reference_manual.info, Node: igraph_laplacian --- Returns the Laplacian matrix of a graph, Up: Spectral properties
13.13.1 igraph_laplacian -- Returns the Laplacian matrix of a graph
-------------------------------------------------------------------
int igraph_laplacian(const igraph_t *graph, igraph_matrix_t *res,
igraph_sparsemat_t *sparseres,
igraph_bool_t normalized,
const igraph_vector_t *weights);
The graph Laplacian matrix is similar to an adjacency matrix but
contains -1's instead of 1's and the vertex degrees are included in the
diagonal. So the result for edge i-j is -1 if i!=j and is equal to the
degree of vertex i if i==j. igraph_laplacian will work on a directed
graph; in this case, the diagonal will contain the out-degrees. Loop
edges will be ignored.
The normalized version of the Laplacian matrix has 1 in the diagonal
and -1/sqrt(d[i]d[j]) if there is an edge from i to j.
The first version of this function was written by Vincent Matossian.
*Arguments:. *
`graph':
Pointer to the graph to convert.
`res':
Pointer to an initialized matrix object, the result is stored
here. It will be resized if needed. If it is a null pointer, then
it is ignored. At least one of `res' and `sparseres' must be a
non-null pointer.
`sparseres':
Pointer to an initialized sparse matrix object, the result is
stored here, if it is not a null pointer. At least one of `res'
and `sparseres' must be a non-null pointer.
`normalized':
Whether to create a normalized Laplacian matrix.
`weights':
An optional vector containing edge weights, to calculate the
weighted Laplacian matrix. Set it to a null pointer to calculate
the unweighted Laplacian.
*Returns:. *
`'
Error code.
Time complexity: O(|V||V|), |V| is the number of vertices in the
graph.
* File examples/simple/igraph_laplacian.c*
File: igraph_reference_manual.info, Node: Non-simple graphs; multiple and loop edges, Next: Mixing patterns, Prev: Spectral properties, Up: Structural Properties of Graphs
13.14 Non-simple graphs: multiple and loop edges
================================================
* Menu:
* igraph_is_simple --- Decides whether the input graph is a simple graph.: igraph_is_simple --- Decides whether the input graph is a simple graph_.
* igraph_is_loop --- Find the loop edges in a graph.: igraph_is_loop --- Find the loop edges in a graph_.
* igraph_is_multiple --- Find the multiple edges in a graph.: igraph_is_multiple --- Find the multiple edges in a graph_.
* igraph_has_multiple --- Check whether the graph has at least one multiple edge.: igraph_has_multiple --- Check whether the graph has at least one multiple edge_.
* igraph_count_multiple --- Count the number of appearances of the edges in a graph.: igraph_count_multiple --- Count the number of appearances of the edges in a graph_.
* igraph_simplify --- Removes loop and/or multiple edges from the graph.: igraph_simplify --- Removes loop and/or multiple edges from the graph_.
File: igraph_reference_manual.info, Node: igraph_is_simple --- Decides whether the input graph is a simple graph_, Next: igraph_is_loop --- Find the loop edges in a graph_, Up: Non-simple graphs; multiple and loop edges
13.14.1 igraph_is_simple -- Decides whether the input graph is a simple graph.
------------------------------------------------------------------------------
int igraph_is_simple(const igraph_t *graph, igraph_bool_t *res);
A graph is a simple graph if it does not contain loop edges and
multiple edges.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a boolean constant, the result is stored here.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_is_loop()' (*note igraph_is_loop --- Find the loop edges
in a graph_::) and `igraph_is_multiple()' (*note
igraph_is_multiple --- Find the multiple edges in a graph_::) to
find the loops and multiple edges, `igraph_simplify()' (*note
igraph_simplify --- Removes loop and/or multiple edges from the
graph_::) to get rid of them, or `igraph_has_multiple()' (*note
igraph_has_multiple --- Check whether the graph has at least one
multiple edge_::) to decide whether there is at least one multiple
edge.
Time complexity: O(|V|+|E|).
File: igraph_reference_manual.info, Node: igraph_is_loop --- Find the loop edges in a graph_, Next: igraph_is_multiple --- Find the multiple edges in a graph_, Prev: igraph_is_simple --- Decides whether the input graph is a simple graph_, Up: Non-simple graphs; multiple and loop edges
13.14.2 igraph_is_loop -- Find the loop edges in a graph.
---------------------------------------------------------
int igraph_is_loop(const igraph_t *graph, igraph_vector_bool_t *res,
igraph_es_t es);
A loop edge is an edge from a vertex to itself.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized boolean vector for storing the result,
it will be resized as needed.
`es':
The edges to check, for all edges supply `igraph_ess_all()' (*note
igraph_ess_all --- Edge set; all edges [immediate version]::) here.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::) to get rid of loop edges.
Time complexity: O(e), the number of edges to check.
* File examples/simple/igraph_is_loop.c*
File: igraph_reference_manual.info, Node: igraph_is_multiple --- Find the multiple edges in a graph_, Next: igraph_has_multiple --- Check whether the graph has at least one multiple edge_, Prev: igraph_is_loop --- Find the loop edges in a graph_, Up: Non-simple graphs; multiple and loop edges
13.14.3 igraph_is_multiple -- Find the multiple edges in a graph.
-----------------------------------------------------------------
int igraph_is_multiple(const igraph_t *graph, igraph_vector_bool_t *res,
igraph_es_t es);
An edge is a multiple edge if there is another edge with the same
head and tail vertices in the graph.
Note that this function returns true only for the second or more
appearances of the multiple edges.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a boolean vector, the result will be stored here. It
will be resized as needed.
`es':
The edges to check. Supply `igraph_ess_all()' (*note
igraph_ess_all --- Edge set; all edges [immediate version]::) if
you want to check all edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_count_multiple()' (*note igraph_count_multiple --- Count
the number of appearances of the edges in a graph_::),
`igraph_has_multiple()' (*note igraph_has_multiple --- Check
whether the graph has at least one multiple edge_::) and
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::).
Time complexity: O(e*d), e is the number of edges to check and d is
the average degree (out-degree in directed graphs) of the vertices at
the tail of the edges.
* File examples/simple/igraph_is_multiple.c*
File: igraph_reference_manual.info, Node: igraph_has_multiple --- Check whether the graph has at least one multiple edge_, Next: igraph_count_multiple --- Count the number of appearances of the edges in a graph_, Prev: igraph_is_multiple --- Find the multiple edges in a graph_, Up: Non-simple graphs; multiple and loop edges
13.14.4 igraph_has_multiple -- Check whether the graph has at least one multiple edge.
--------------------------------------------------------------------------------------
int igraph_has_multiple(const igraph_t *graph, igraph_bool_t *res);
An edge is a multiple edge if there is another edge with the same
head and tail vertices in the graph.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a boolean variable, the result will be stored here.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_count_multiple()' (*note igraph_count_multiple --- Count
the number of appearances of the edges in a graph_::),
`igraph_is_multiple()' (*note igraph_is_multiple --- Find the
multiple edges in a graph_::) and `igraph_simplify()' (*note
igraph_simplify --- Removes loop and/or multiple edges from the
graph_::).
Time complexity: O(e*d), e is the number of edges to check and d is
the average degree (out-degree in directed graphs) of the vertices at
the tail of the edges.
* File examples/simple/igraph_has_multiple.c*
File: igraph_reference_manual.info, Node: igraph_count_multiple --- Count the number of appearances of the edges in a graph_, Next: igraph_simplify --- Removes loop and/or multiple edges from the graph_, Prev: igraph_has_multiple --- Check whether the graph has at least one multiple edge_, Up: Non-simple graphs; multiple and loop edges
13.14.5 igraph_count_multiple -- Count the number of appearances of the edges in a graph.
-----------------------------------------------------------------------------------------
int igraph_count_multiple(const igraph_t *graph, igraph_vector_t *res, igraph_es_t es);
If the graph has no multiple edges then the result vector will be
filled with ones. (An edge is a multiple edge if there is another edge
with the same head and tail vertices in the graph.)
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a vector, the result will be stored here. It will be
resized as needed.
`es':
The edges to check. Supply `igraph_ess_all()' (*note
igraph_ess_all --- Edge set; all edges [immediate version]::) if
you want to check all edges.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_is_multiple()' (*note igraph_is_multiple --- Find the
multiple edges in a graph_::) and `igraph_simplify()' (*note
igraph_simplify --- Removes loop and/or multiple edges from the
graph_::).
Time complexity: O(e*d), e is the number of edges to check and d is
the average degree (out-degree in directed graphs) of the vertices at
the tail of the edges.
File: igraph_reference_manual.info, Node: igraph_simplify --- Removes loop and/or multiple edges from the graph_, Prev: igraph_count_multiple --- Count the number of appearances of the edges in a graph_, Up: Non-simple graphs; multiple and loop edges
13.14.6 igraph_simplify -- Removes loop and/or multiple edges from the graph.
-----------------------------------------------------------------------------
int igraph_simplify(igraph_t *graph, igraph_bool_t multiple,
igraph_bool_t loops,
const igraph_attribute_combination_t *edge_comb);
*Arguments:. *
`graph':
The graph object.
`multiple':
Logical, if true, multiple edges will be removed.
`loops':
Logical, if true, loops (self edges) will be removed.
`edge_comb':
What to do with the edge attributes. See the igraph manual section
about attributes for details.
*Returns:. *
`'
Error code: `IGRAPH_ENOMEM' if we are out of memory.
Time complexity: O(|V|+|E|).
* File examples/simple/igraph_simplify.c*
File: igraph_reference_manual.info, Node: Mixing patterns, Next: K-Cores, Prev: Non-simple graphs; multiple and loop edges, Up: Structural Properties of Graphs
13.15 Mixing patterns
=====================
* Menu:
* igraph_assortativity_nominal --- Assortativity of a graph based on vertex categories::
* igraph_assortativity --- Assortativity based on numeric properties of vertices::
* igraph_assortativity_degree --- Assortativity of a graph based on vertex degree::
File: igraph_reference_manual.info, Node: igraph_assortativity_nominal --- Assortativity of a graph based on vertex categories, Next: igraph_assortativity --- Assortativity based on numeric properties of vertices, Up: Mixing patterns
13.15.1 igraph_assortativity_nominal -- Assortativity of a graph based on vertex categories
-------------------------------------------------------------------------------------------
int igraph_assortativity_nominal(const igraph_t *graph,
const igraph_vector_t *types,
igraph_real_t *res,
igraph_bool_t directed);
Assuming the vertices of the input graph belong to different
categories, this function calculates the assortativity coefficient of
the graph. The assortativity coefficient is between minus one and one
and it is one if all connections stay within categories, it is minus
one, if the network is perfectly disassortative. For a randomly
connected network it is (asymptotically) zero.
See equation (2) in M. E. J. Newman: Mixing patterns in networks,
Phys. Rev. E 67, 026126 (2003) (http://arxiv.org/abs/cond-mat/0209450
(http://arxiv.org/abs/cond-mat/0209450)) for the proper definition.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`types':
Vector giving the vertex types. They are assumed to be integer
numbers, starting with zero.
`res':
Pointer to a real variable, the result is stored here.
`directed':
Boolean, it gives whether to consider edge directions in a
directed graph. It is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|E|+t), |E| is the number of edges, t is the
number of vertex types.
*See also:. *
`'
`igraph_assortativity' (*note igraph_assortativity ---
Assortativity based on numeric properties of vertices::) if the
vertex types are defines by numeric values (e.g. vertex degree),
instead of categories.
* File examples/simple/assortativity.c*
File: igraph_reference_manual.info, Node: igraph_assortativity --- Assortativity based on numeric properties of vertices, Next: igraph_assortativity_degree --- Assortativity of a graph based on vertex degree, Prev: igraph_assortativity_nominal --- Assortativity of a graph based on vertex categories, Up: Mixing patterns
13.15.2 igraph_assortativity -- Assortativity based on numeric properties of vertices
-------------------------------------------------------------------------------------
int igraph_assortativity(const igraph_t *graph,
const igraph_vector_t *types1,
const igraph_vector_t *types2,
igraph_real_t *res,
igraph_bool_t directed);
This function calculates the assortativity coefficient of the input
graph. This coefficient is basically the correlation between the actual
connectivity patterns of the vertices and the pattern expected from the
distribution of the vertex types.
See equation (21) in M. E. J. Newman: Mixing patterns in networks,
Phys. Rev. E 67, 026126 (2003) (http://arxiv.org/abs/cond-mat/0209450
(http://arxiv.org/abs/cond-mat/0209450)) for the proper definition. The
actual calculation is performed using equation (26) in the same paper
for directed graphs, and equation (4) in M. E. J. Newman: Assortative
mixing in networks, Phys. Rev. Lett. 89, 208701 (2002)
(http://arxiv.org/abs/cond-mat/0205405/
(http://arxiv.org/abs/cond-mat/0205405/)) for undirected graphs.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`types1':
The vertex values, these can be arbitrary numeric values.
`types2':
A second value vector to be using for the incoming edges when
calculating assortativity for a directed graph. Supply a null
pointer here if you want to use the same values for outgoing and
incoming edges. This argument is ignored (with a warning) if it is
not a null pointer and undirected assortativity coefficient is
being calculated.
`res':
Pointer to a real variable, the result is stored here.
`directed':
Boolean, whether to consider edge directions for directed graphs.
It is ignored for undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|E|), linear in the number of edges of the graph.
*See also:. *
`'
`igraph_assortativity_nominal()' (*note
igraph_assortativity_nominal --- Assortativity of a graph based on
vertex categories::) if you have discrete vertex categories
instead of numeric labels, and `igraph_assortativity_degree()'
(*note igraph_assortativity_degree --- Assortativity of a graph
based on vertex degree::) for the special case of assortativity
based on vertex degree.
* File examples/simple/assortativity.c*
File: igraph_reference_manual.info, Node: igraph_assortativity_degree --- Assortativity of a graph based on vertex degree, Prev: igraph_assortativity --- Assortativity based on numeric properties of vertices, Up: Mixing patterns
13.15.3 igraph_assortativity_degree -- Assortativity of a graph based on vertex degree
--------------------------------------------------------------------------------------
int igraph_assortativity_degree(const igraph_t *graph,
igraph_real_t *res,
igraph_bool_t directed);
Assortativity based on vertex degree, please see the discussion at
the documentation of `igraph_assortativity()' (*note
igraph_assortativity --- Assortativity based on numeric properties of
vertices::) for details.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`res':
Pointer to a real variable, the result is stored here.
`directed':
Boolean, whether to consider edge directions for directed graphs.
This argument is ignored for undirected graphs. Supply 1 (=TRUE)
here to do the natural thing, i.e. use directed version of the
measure for directed graphs and the undirected version for
undirected graphs.
*Returns:. *
`'
Error code.
Time complexity: O(|E|+|V|), |E| is the number of edges, |V| is the
number of vertices.
*See also:. *
`'
`igraph_assortativity()' (*note igraph_assortativity ---
Assortativity based on numeric properties of vertices::) for the
general function calculating assortativity for any kind of numeric
vertex values.
* File examples/simple/assortativity.c*
File: igraph_reference_manual.info, Node: K-Cores, Next: Topological sorting; directed acyclic graphs, Prev: Mixing patterns, Up: Structural Properties of Graphs
13.16 K-Cores
=============
* Menu:
* igraph_coreness --- Finding the coreness of the vertices in a network.: igraph_coreness --- Finding the coreness of the vertices in a network_.
File: igraph_reference_manual.info, Node: igraph_coreness --- Finding the coreness of the vertices in a network_, Up: K-Cores
13.16.1 igraph_coreness -- Finding the coreness of the vertices in a network.
-----------------------------------------------------------------------------
int igraph_coreness(const igraph_t *graph, igraph_vector_t *cores,
igraph_neimode_t mode);
The k-core of a graph is a maximal subgraph in which each vertex has
at least degree k. (Degree here means the degree in the subgraph of
course.). The coreness of a vertex is the highest order of a k-core
containing the vertex.
This function implements the algorithm presented in Vladimir
Batagelj, Matjaz Zaversnik: An O(m) Algorithm for Cores Decomposition
of Networks.
*Arguments:. *
`graph':
The input graph.
`cores':
Pointer to an initialized vector, the result of the computation
will be stored here. It will be resized as needed. For each vertex
it contains the highest order of a core containing the vertex.
`mode':
For directed graph it specifies whether to calculate in-cores,
out-cores or the undirected version. It is ignored for undirected
graphs. Possible values: `IGRAPH_ALL' undirected version,
`IGRAPH_IN' in-cores, `IGRAPH_OUT' out-cores.
*Returns:. *
`'
Error code.
Time complexity: O(|E|), the number of edges.
File: igraph_reference_manual.info, Node: Topological sorting; directed acyclic graphs, Next: Maximum cardinality search; graph decomposition; chordal graphs, Prev: K-Cores, Up: Structural Properties of Graphs
13.17 Topological sorting, directed acyclic graphs
==================================================
* Menu:
* igraph_is_dag --- Checks whether a graph is a directed acyclic graph (DAG) or not.: igraph_is_dag --- Checks whether a graph is a directed acyclic graph [DAG] or not_.
* igraph_topological_sorting --- Calculate a possible topological sorting of the graph.: igraph_topological_sorting --- Calculate a possible topological sorting of the graph_.
* igraph_feedback_arc_set --- Calculates a feedback arc set of the graph using different::
File: igraph_reference_manual.info, Node: igraph_is_dag --- Checks whether a graph is a directed acyclic graph [DAG] or not_, Next: igraph_topological_sorting --- Calculate a possible topological sorting of the graph_, Up: Topological sorting; directed acyclic graphs
13.17.1 igraph_is_dag -- Checks whether a graph is a directed acyclic graph (DAG) or not.
-----------------------------------------------------------------------------------------
int igraph_is_dag(const igraph_t* graph, igraph_bool_t *res);
A directed acyclic graph (DAG) is a directed graph with no cycles.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a boolean constant, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), where |V| and |E| are the number of
vertices and edges in the original input graph.
*See also:. *
`'
`igraph_topological_sorting()' (*note igraph_topological_sorting
--- Calculate a possible topological sorting of the graph_::) to
get a possible topological sorting of a DAG.
File: igraph_reference_manual.info, Node: igraph_topological_sorting --- Calculate a possible topological sorting of the graph_, Next: igraph_feedback_arc_set --- Calculates a feedback arc set of the graph using different, Prev: igraph_is_dag --- Checks whether a graph is a directed acyclic graph [DAG] or not_, Up: Topological sorting; directed acyclic graphs
13.17.2 igraph_topological_sorting -- Calculate a possible topological sorting of the graph.
--------------------------------------------------------------------------------------------
int igraph_topological_sorting(const igraph_t* graph, igraph_vector_t *res,
igraph_neimode_t mode);
A topological sorting of a directed acyclic graph is a linear
ordering of its nodes where each node comes before all nodes to which
it has edges. Every DAG has at least one topological sort, and may have
many. This function returns a possible topological sort among them. If
the graph is not acyclic (it has at least one cycle), a partial
topological sort is returned and a warning is issued.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a vector, the result will be stored here. It will be
resized if needed.
`mode':
Specifies how to use the direction of the edges. For
`IGRAPH_OUT', the sorting order ensures that each node comes
before all nodes to which it has edges, so nodes with no incoming
edges go first. For `IGRAPH_IN', it is quite the opposite: each
node comes before all nodes from which it receives edges. Nodes
with no outgoing edges go first.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), where |V| and |E| are the number of
vertices and edges in the original input graph.
*See also:. *
`'
`igraph_is_dag()' (*note igraph_is_dag --- Checks whether a graph
is a directed acyclic graph [DAG] or not_::) if you are only
interested in whether a given graph is a DAG or not, or
`igraph_feedback_arc_set()' (*note igraph_feedback_arc_set ---
Calculates a feedback arc set of the graph using different::) to
find a set of edges whose removal makes the graph a DAG.
* File examples/simple/igraph_topological_sorting.c*
File: igraph_reference_manual.info, Node: igraph_feedback_arc_set --- Calculates a feedback arc set of the graph using different, Prev: igraph_topological_sorting --- Calculate a possible topological sorting of the graph_, Up: Topological sorting; directed acyclic graphs
13.17.3 igraph_feedback_arc_set -- Calculates a feedback arc set of the graph using different
---------------------------------------------------------------------------------------------
int igraph_feedback_arc_set(const igraph_t *graph, igraph_vector_t *result,
const igraph_vector_t *weights, igraph_fas_algorithm_t algo);
algorithms.
A feedback arc set is a set of edges whose removal makes the graph
acyclic. We are usually interested in _minimum_ feedback arc sets,
i.e. sets of edges whose total weight is minimal among all the feedback
arc sets.
For undirected graphs, the problem is simple: one has to find a
maximum weight spanning tree and then remove all the edges not in the
spanning tree. For directed graphs, this is an NP-hard problem, and
various heuristics are usually used to find an approximate solution to
the problem. This function implements a few of these heuristics.
*Arguments:. *
`graph':
The graph object.
`result':
An initialized vector, the result will be returned here.
`weights':
Weight vector or NULL if no weights are specified.
`algo':
The algorithm to use to solve the problem if the graph is directed.
Possible values:
`IGRAPH_FAS_EXACT_IP'
Finds a _minimum_ feedback arc set using integer programming
(IP). The complexity of this algorithm is exponential of
course.
`IGRAPH_FAS_APPROX_EADES'
Finds a feedback arc set using the heuristic of Eades, Lin and
Smyth (1993). This is guaranteed to be smaller than |E|/2 -
|V|/6, and it is linear in the number of edges (i.e. O(|E|)).
For more details, see Eades P, Lin X and Smyth WF: A fast and
effective heuristic for the feedback arc set problem. In:
Proc Inf Process Lett 319-323, 1993.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL' if an unknown method was specified or
the weight vector is invalid.
* File examples/simple/igraph_feedback_arc_set.c*
* File examples/simple/igraph_feedback_arc_set_ip.c*
Time complexity: depends on `algo', see the time complexities there.
File: igraph_reference_manual.info, Node: Maximum cardinality search; graph decomposition; chordal graphs, Next: Matchings, Prev: Topological sorting; directed acyclic graphs, Up: Structural Properties of Graphs
13.18 Maximum cardinality search, graph decomposition, chordal graphs
=====================================================================
* Menu:
* igraph_maximum_cardinality_search --- Maximum cardinality search::
* igraph_is_chordal --- Decides whether a graph is chordal::
File: igraph_reference_manual.info, Node: igraph_maximum_cardinality_search --- Maximum cardinality search, Next: igraph_is_chordal --- Decides whether a graph is chordal, Up: Maximum cardinality search; graph decomposition; chordal graphs
13.18.1 igraph_maximum_cardinality_search -- Maximum cardinality search
-----------------------------------------------------------------------
int igraph_maximum_cardinality_search(const igraph_t *graph,
igraph_vector_t *alpha,
igraph_vector_t *alpham1);
This function implements the maximum cardinality search algorithm
discussed in Robert E Tarjan and Mihalis Yannakakis: Simple linear-time
algorithms to test chordality of graphs, test acyclicity of
hypergraphs, and selectively reduce acyclic hypergraphs. SIAM Journal
of Computation 13, 566-579, 1984.
*Arguments:. *
`graph':
The input graph. Can be directed, but the direction of the edges
is ignored.
`alpha':
Pointer to an initialized vector, the result is stored here. It
will be resized, as needed. Upon return it contains the rank of
the each vertex.
`alpham1':
Pointer to an initialized vector or a `NULL' pointer. If not
`NULL', then the inverse of `alpha' is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in terms of the number of
vertices and edges.
*See also:. *
`'
`igraph_is_chordal()' (*note igraph_is_chordal --- Decides whether
a graph is chordal::).
File: igraph_reference_manual.info, Node: igraph_is_chordal --- Decides whether a graph is chordal, Prev: igraph_maximum_cardinality_search --- Maximum cardinality search, Up: Maximum cardinality search; graph decomposition; chordal graphs
13.18.2 igraph_is_chordal -- Decides whether a graph is chordal
---------------------------------------------------------------
int igraph_is_chordal(const igraph_t *graph,
const igraph_vector_t *alpha,
const igraph_vector_t *alpham1,
igraph_bool_t *chordal,
igraph_vector_t *fill_in,
igraph_t *newgraph);
A graph is chordal if each of its cycles of four or more nodes has a
chord, which is an edge joining two nodes that are not adjacent in the
cycle. An equivalent definition is that any chordless cycles have at
most three nodes. If either `alpha' or `alpha1' is given, then the
other is calculated by taking simply the inverse. If neither are given,
then `igraph_maximum_cardinality_search()' (*note
igraph_maximum_cardinality_search --- Maximum cardinality search::) is
called to calculate them.
*Arguments:. *
`graph':
The input graph, it might be directed, but edge direction is
ignored.
`alpha':
Either an alpha vector coming from
`igraph_maximum_cardinality_search()' (*note
igraph_maximum_cardinality_search --- Maximum cardinality
search::) (on the same graph), or a null pointer.
`alpham1':
Either an inverse alpha vector coming from
`igraph_maximum_cardinality_search()' (*note
igraph_maximum_cardinality_search --- Maximum cardinality
search::) (on the same graph) or a null pointer.
`chordal':
Pointer to a boolean, the result is stored here.
`fill_in':
Pointer to an initialized vector, or a null pointer. If not a null
pointer, then the fill-in of the graph is stored here. The fill-in
is the set of edges that are needed to make the graph chordal. The
vector is resized as needed.
`newgraph':
Pointer to an uninitialized graph, or a null pointer. If not a
null pointer, then a new triangulated graph is created here. This
essentially means adding the fill-in edges to the original graph.
*Returns:. *
`'
Error code.
Time complexity: O(n).
*See also:. *
`'
`igraph_maximum_cardinality_search()' (*note
igraph_maximum_cardinality_search --- Maximum cardinality
search::).
File: igraph_reference_manual.info, Node: Matchings, Next: Line graphs, Prev: Maximum cardinality search; graph decomposition; chordal graphs, Up: Structural Properties of Graphs
13.19 Matchings
===============
* Menu:
* igraph_is_matching --- Checks whether the given matching is valid for the given graph.: igraph_is_matching --- Checks whether the given matching is valid for the given graph_.
* igraph_is_maximal_matching --- Checks whether a matching in a graph is maximal.: igraph_is_maximal_matching --- Checks whether a matching in a graph is maximal_.
* igraph_maximum_bipartite_matching --- Calculates a maximum matching in a bipartite graph.: igraph_maximum_bipartite_matching --- Calculates a maximum matching in a bipartite graph_.
File: igraph_reference_manual.info, Node: igraph_is_matching --- Checks whether the given matching is valid for the given graph_, Next: igraph_is_maximal_matching --- Checks whether a matching in a graph is maximal_, Up: Matchings
13.19.1 igraph_is_matching -- Checks whether the given matching is valid for the given graph.
---------------------------------------------------------------------------------------------
int igraph_is_matching(const igraph_t* graph,
const igraph_vector_bool_t* types, const igraph_vector_long_t* matching,
igraph_bool_t* result);
This function checks a matching vector and verifies whether its
length matches the number of vertices in the given graph, its values
are between -1 (inclusive) and the number of vertices (exclusive), and
whether there exists a corresponding edge in the graph for every
matched vertex pair. For bipartite graphs, it also verifies whether
the matched vertices are in different parts of the graph.
*Arguments:. *
`graph':
The input graph. It can be directed but the edge directions will
be ignored.
`types':
If the graph is bipartite and you are interested in bipartite
matchings only, pass the vertex types here. If the graph is
non-bipartite, simply pass `NULL'.
`matching':
The matching itself. It must be a vector where element i contains
the ID of the vertex that vertex i is matched to, or -1 if vertex
i is unmatched.
`result':
Pointer to a boolean variable, the result will be returned here.
*See also:. *
`'
`igraph_is_maximal_matching()' (*note igraph_is_maximal_matching
--- Checks whether a matching in a graph is maximal_::) if you are
also interested in whether the matching is maximal (i.e.
non-extendable).
Time complexity: O(|V|+|E|) where |V| is the number of vertices and
|E| is the number of edges.
* File examples/simple/igraph_maximum_bipartite_matching.c*
File: igraph_reference_manual.info, Node: igraph_is_maximal_matching --- Checks whether a matching in a graph is maximal_, Next: igraph_maximum_bipartite_matching --- Calculates a maximum matching in a bipartite graph_, Prev: igraph_is_matching --- Checks whether the given matching is valid for the given graph_, Up: Matchings
13.19.2 igraph_is_maximal_matching -- Checks whether a matching in a graph is maximal.
--------------------------------------------------------------------------------------
int igraph_is_maximal_matching(const igraph_t* graph,
const igraph_vector_bool_t* types, const igraph_vector_long_t* matching,
igraph_bool_t* result);
A matching is maximal if and only if there exists no unmatched
vertex in a graph such that one of its neighbors is also unmatched.
*Arguments:. *
`graph':
The input graph. It can be directed but the edge directions will
be ignored.
`types':
If the graph is bipartite and you are interested in bipartite
matchings only, pass the vertex types here. If the graph is
non-bipartite, simply pass `NULL'.
`matching':
The matching itself. It must be a vector where element i contains
the ID of the vertex that vertex i is matched to, or -1 if vertex
i is unmatched.
`result':
Pointer to a boolean variable, the result will be returned here.
*See also:. *
`'
`igraph_is_matching()' (*note igraph_is_matching --- Checks
whether the given matching is valid for the given graph_::) if you
are only interested in whether a matching vector is valid for a
given graph.
Time complexity: O(|V|+|E|) where |V| is the number of vertices and
|E| is the number of edges.
* File examples/simple/igraph_maximum_bipartite_matching.c*
File: igraph_reference_manual.info, Node: igraph_maximum_bipartite_matching --- Calculates a maximum matching in a bipartite graph_, Prev: igraph_is_maximal_matching --- Checks whether a matching in a graph is maximal_, Up: Matchings
13.19.3 igraph_maximum_bipartite_matching -- Calculates a maximum matching in a bipartite graph.
------------------------------------------------------------------------------------------------
int igraph_maximum_bipartite_matching(const igraph_t* graph,
const igraph_vector_bool_t* types, igraph_integer_t* matching_size,
igraph_real_t* matching_weight, igraph_vector_long_t* matching,
const igraph_vector_t* weights, igraph_real_t eps);
A matching in a bipartite graph is a partial assignment of vertices
of the first kind to vertices of the second kind such that each vertex
of the first kind is matched to at most one vertex of the second kind
and vice versa, and matched vertices must be connected by an edge in
the graph. The size (or cardinality) of a matching is the number of
edges. A matching is a maximum matching if there exists no other
matching with larger cardinality. For weighted graphs, a maximum
matching is a matching whose edges have the largest possible total
weight among all possible matchings.
Maximum matchings in bipartite graphs are found by the push-relabel
algorithm with greedy initialization and a global relabeling after
every n/2 steps where n is the number of vertices in the graph.
References: Cherkassky BV, Goldberg AV, Martin P, Setubal JC and
Stolfi J: Augment or push: A computational study of bipartite matching
and unit-capacity flow algorithms. ACM Journal of Experimental
Algorithmics 3, 1998.
Kaya K, Langguth J, Manne F and Ucar B: Experiments on
push-relabel-based maximum cardinality matching algorithms for
bipartite graphs. Technical Report TR/PA/11/33 of the Centre Europeen
de Recherche et de Formation Avancee en Calcul Scientifique, 2011.
*Arguments:. *
`graph':
The input graph. It can be directed but the edge directions will
be ignored.
`types':
Boolean vector giving the vertex types of the graph.
`matching_size':
The size of the matching (i.e. the number of matched vertex pairs
will be returned here). It may be `NULL' if you don't need this.
`matching_weight':
The weight of the matching if the edges are weighted, or the size
of the matching again if the edges are unweighted. It may be
`NULL' if you don't need this.
`matching':
The matching itself. It must be a vector where element i contains
the ID of the vertex that vertex i is matched to, or -1 if vertex
i is unmatched.
`weights':
A null pointer (=no edge weights), or a vector giving the weights
of the edges. Note that the algorithm is stable only for integer
weights.
`eps':
A small real number used in equality tests in the weighted
bipartite matching algorithm. Two real numbers are considered
equal in the algorithm if their difference is smaller than `eps'.
This is required to avoid the accumulation of numerical errors. It
is advised to pass a value derived from the `DBL_EPSILON' constant
in `float'.h here. If you are running the algorithm with no
`weights' vector, this argument is ignored.
*Returns:. *
`'
Error code.
Time complexity: O(sqrt(|V|) |E|) for unweighted graphs (according
to the technical report referenced above), O(|V||E|) for weighted
graphs.
* File examples/simple/igraph_maximum_bipartite_matching.c*
File: igraph_reference_manual.info, Node: Line graphs, Next: Unfolding a graph into a tree, Prev: Matchings, Up: Structural Properties of Graphs
13.20 Line graphs
=================
* Menu:
* igraph_linegraph --- Create the line graph of a graph.: igraph_linegraph --- Create the line graph of a graph_.
File: igraph_reference_manual.info, Node: igraph_linegraph --- Create the line graph of a graph_, Up: Line graphs
13.20.1 igraph_linegraph -- Create the line graph of a graph.
-------------------------------------------------------------
int igraph_linegraph(const igraph_t *graph, igraph_t *linegraph);
The line graph L(G) of a G undirected graph is defined as follows.
L(G) has one vertex for each edge in G and two vertices in L(G) are
connected by an edge if their corresponding edges share an end point.
The line graph L(G) of a G directed graph is slightly different,
L(G) has one vertex for each edge in G and two vertices in L(G) are
connected by a directed edge if the target of the first vertex's
corresponding edge is the same as the source of the second vertex's
corresponding edge.
Edge _i_ in the original graph will correspond to vertex _i_ in the
line graph.
The first version of this function was contributed by Vincent
Matossian, thanks.
*Arguments:. *
`graph':
The input graph, may be directed or undirected.
`linegraph':
Pointer to an uninitialized graph object, the result is stored
here.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), the number of edges plus the number of
vertices.
File: igraph_reference_manual.info, Node: Unfolding a graph into a tree, Next: Other Operations, Prev: Line graphs, Up: Structural Properties of Graphs
13.21 Unfolding a graph into a tree
===================================
* Menu:
* igraph_unfold_tree --- Unfolding a graph into a tree, by possibly multiplicating its vertices.: igraph_unfold_tree --- Unfolding a graph into a tree; by possibly multiplicating its vertices_.
File: igraph_reference_manual.info, Node: igraph_unfold_tree --- Unfolding a graph into a tree; by possibly multiplicating its vertices_, Up: Unfolding a graph into a tree
13.21.1 igraph_unfold_tree -- Unfolding a graph into a tree, by possibly multiplicating its vertices.
-----------------------------------------------------------------------------------------------------
int igraph_unfold_tree(const igraph_t *graph, igraph_t *tree,
igraph_neimode_t mode, const igraph_vector_t *roots,
igraph_vector_t *vertex_index);
A graph is converted into a tree (or forest, if it is unconnected),
by performing a breadth-first search on it, and replicating vertices
that were found a second, third, etc. time.
*Arguments:. *
`graph':
The input graph, it can be either directed or undirected.
`tree':
Pointer to an uninitialized graph object, the result is stored
here.
`mode':
For directed graphs; whether to follow paths along edge directions
(`IGRAPH_OUT'), or the opposite (`IGRAPH_IN'), or ignore edge
directions completely (`IGRAPH_ALL'). It is ignored for undirected
graphs.
`roots':
A numeric vector giving the root vertex, or vertices (if the graph
is not connected), to start from.
`vertex_index':
Pointer to an initialized vector, or a null pointer. If not a null
pointer, then a mapping from the vertices in the new graph to the
ones in the original is created here.
*Returns:. *
`'
Error code.
Time complexity: O(n+m), linear in the number vertices and edges.
File: igraph_reference_manual.info, Node: Other Operations, Prev: Unfolding a graph into a tree, Up: Structural Properties of Graphs
13.22 Other Operations
======================
* Menu:
* igraph_density --- Calculate the density of a graph.: igraph_density --- Calculate the density of a graph_.
* igraph_reciprocity --- Calculates the reciprocity of a directed graph.: igraph_reciprocity --- Calculates the reciprocity of a directed graph_.
* igraph_diversity --- Structural diversity index of the vertices::
* igraph_is_mutual --- Check whether the edges of a directed graph are mutual.: igraph_is_mutual --- Check whether the edges of a directed graph are mutual_.
* igraph_avg_nearest_neighbor_degree --- Average nearest neighbor degree.: igraph_avg_nearest_neighbor_degree --- Average nearest neighbor degree_.
* igraph_get_adjacency --- Returns the adjacency matrix of a graph::
* igraph_get_stochastic --- Stochastic adjacency matrix of a graph::
* igraph_get_stochastic_sparsemat --- Stochastic adjacency matrix of a graph::
* igraph_get_edgelist --- Returns the list of edges in a graph::
* igraph_contract_vertices --- Replace multiple vertices with a single one.: igraph_contract_vertices --- Replace multiple vertices with a single one_.
File: igraph_reference_manual.info, Node: igraph_density --- Calculate the density of a graph_, Next: igraph_reciprocity --- Calculates the reciprocity of a directed graph_, Up: Other Operations
13.22.1 igraph_density -- Calculate the density of a graph.
-----------------------------------------------------------
int igraph_density(const igraph_t *graph, igraph_real_t *res,
igraph_bool_t loops);
The density of a graph is simply the ratio number of edges and the
number of possible edges. Note that density is ill-defined for graphs
with multiple and/or loop edges, so consider calling
`igraph_simplify()' (*note igraph_simplify --- Removes loop and/or
multiple edges from the graph_::) on the graph if you know that it
contains multiple or loop edges.
*Arguments:. *
`graph':
The input graph object.
`res':
Pointer to a real number, the result will be stored here.
`loops':
Logical constant, whether to include loops in the calculation. If
this constant is TRUE then loop edges are thought to be possible
in the graph (this does not necessarily mean that the graph really
contains any loops). If this is FALSE then the result is only
correct if the graph does not contain loops.
*Returns:. *
`'
Error code.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_reciprocity --- Calculates the reciprocity of a directed graph_, Next: igraph_diversity --- Structural diversity index of the vertices, Prev: igraph_density --- Calculate the density of a graph_, Up: Other Operations
13.22.2 igraph_reciprocity -- Calculates the reciprocity of a directed graph.
-----------------------------------------------------------------------------
int igraph_reciprocity(const igraph_t *graph, igraph_real_t *res,
igraph_bool_t ignore_loops,
igraph_reciprocity_t mode);
The measure of reciprocity defines the proportion of mutual
connections, in a directed graph. It is most commonly defined as the
probability that the opposite counterpart of a directed edge is also
included in the graph. In adjacency matrix notation: ` sum(i, j,
(A.*A')ij) / sum(i, j, Aij)' , where ` A.*A'' is the element-wise
product of matrix ` A' and its transpose. This measure is calculated
if the `mode' argument is `IGRAPH_RECIPROCITY_DEFAULT'.
Prior to igraph version 0.6, another measure was implemented,
defined as the probability of mutual connection between a vertex pair
if we know that there is a (possibly non-mutual) connection between
them. In other words, (unordered) vertex pairs are classified into
three groups: (1) disconnected, (2) non-reciprocally connected, (3)
reciprocally connected. The result is the size of group (3), divided
by the sum of group sizes (2)+(3). This measure is calculated if `mode'
is `IGRAPH_RECIPROCITY_RATIO'.
*Arguments:. *
`graph':
The graph object.
`res':
Pointer to an `igraph_real_t' which will contain the result.
`ignore_loops':
Whether to ignore loop edges.
`mode':
Type of reciprocity to calculate, possible values are
`IGRAPH_RECIPROCITY_DEFAULT' and `IGRAPH_RECIPROCITY_RATIO',
please see their description above.
*Returns:. *
`'
Error code: `IGRAPH_EINVAL': graph has no edges `IGRAPH_ENOMEM':
not enough memory for temporary data.
Time complexity: O(|V|+|E|), |V| is the number of vertices, |E| is
the number of edges.
* File examples/simple/igraph_reciprocity.c*
File: igraph_reference_manual.info, Node: igraph_diversity --- Structural diversity index of the vertices, Next: igraph_is_mutual --- Check whether the edges of a directed graph are mutual_, Prev: igraph_reciprocity --- Calculates the reciprocity of a directed graph_, Up: Other Operations
13.22.3 igraph_diversity -- Structural diversity index of the vertices
----------------------------------------------------------------------
int igraph_diversity(igraph_t *graph, const igraph_vector_t *weights,
igraph_vector_t *res, const igraph_vs_t vids);
This measure was defined in Nathan Eagle, Michael Macy and Rob
Claxton: Network Diversity and Economic Development, Science 328,
1029-1031, 2010.
It is simply the (normalized) Shannon entropy of the incident edges'
weights. D(i)=H(i)/log(k[i]), and H(i) = -sum(p[i,j] log(p[i,j]),
j=1..k[i]), where p[i,j]=w[i,j]/sum(w[i,l], l=1..k[i]), k[i] is the
(total) degree of vertex i, and w[i,j] is the weight of the edge(s)
between vertex i and j.
*Arguments:. *
`graph':
The input graph, edge directions are ignored.
`weights':
The edge weights, in the order of the edge ids, must have
appropriate length.
`res':
An initialized vector, the results are stored here.
`vids':
Vector with the vertex ids for which to calculate the measure.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear.
File: igraph_reference_manual.info, Node: igraph_is_mutual --- Check whether the edges of a directed graph are mutual_, Next: igraph_avg_nearest_neighbor_degree --- Average nearest neighbor degree_, Prev: igraph_diversity --- Structural diversity index of the vertices, Up: Other Operations
13.22.4 igraph_is_mutual -- Check whether the edges of a directed graph are mutual.
-----------------------------------------------------------------------------------
int igraph_is_mutual(igraph_t *graph, igraph_vector_bool_t *res, igraph_es_t es);
An (A,B) edge is mutual if the graph contains the (B,A) edge, too.
An undirected graph only has mutual edges, by definition.
Edge multiplicity is not considered here, e.g. if there are two
(A,B) edges and one (B,A) edge, then all three are considered to be
mutual.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized vector, the result is stored here.
`es':
The sequence of edges to check. Supply ` igraph_ess_all()' for
all edges, see `igraph_ess_all()' (*note igraph_ess_all --- Edge
set; all edges [immediate version]::).
*Returns:. *
`'
Error code.
Time complexity: O(n log(d)), n is the number of edges supplied, d
is the maximum in-degree of the vertices that are targets of the
supplied edges. An upper limit of the time complexity is O(n log(|E|)),
|E| is the number of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_avg_nearest_neighbor_degree --- Average nearest neighbor degree_, Next: igraph_get_adjacency --- Returns the adjacency matrix of a graph, Prev: igraph_is_mutual --- Check whether the edges of a directed graph are mutual_, Up: Other Operations
13.22.5 igraph_avg_nearest_neighbor_degree -- Average nearest neighbor degree.
------------------------------------------------------------------------------
int igraph_avg_nearest_neighbor_degree(const igraph_t *graph,
igraph_vs_t vids,
igraph_vector_t *knn,
igraph_vector_t *knnk,
const igraph_vector_t *weights);
Calculates the average degree of the neighbors for each vertex, and
optionally, the same quantity in the function of vertex degree.
For isolate vertices `knn' is set to `IGRAPH_NAN'. The same is done
in `knnk' for vertex degrees that don't appear in the graph.
*Arguments:. *
`graph':
The input graph, it can be directed but the directedness of the
edges is ignored.
`vids':
The vertices for which the calculation is performed.
`knn':
Pointer to an initialized vector, the result will be stored here.
It will be resized as needed. Supply a NULL pointer here, if you
only want to calculate `knnk'.
`knnk':
Pointer to an initialized vector, the average nearest neighbor
degree in the function of vertex degree is stored here. The first
(zeroth) element is for degree one vertices, etc. Supply a NULL
pointer here if you don't want to calculate this.
`weights':
Optional edge weights. Supply a null pointer here for the
non-weighted version. If this is not a null pointer, then the
strength of the vertices is used instead of the normal vertex
degree, see `igraph_strength()' (*note igraph_strength ---
Strength of the vertices; weighted vertex degree in other
words_::).
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
* File examples/simple/igraph_knn.c*
File: igraph_reference_manual.info, Node: igraph_get_adjacency --- Returns the adjacency matrix of a graph, Next: igraph_get_stochastic --- Stochastic adjacency matrix of a graph, Prev: igraph_avg_nearest_neighbor_degree --- Average nearest neighbor degree_, Up: Other Operations
13.22.6 igraph_get_adjacency -- Returns the adjacency matrix of a graph
-----------------------------------------------------------------------
int igraph_get_adjacency(const igraph_t *graph, igraph_matrix_t *res,
igraph_get_adjacency_t type, igraph_bool_t eids);
The result is an incidence matrix, it contains numbers greater than
one if there are multiple edges in the graph.
*Arguments:. *
`graph':
Pointer to the graph to convert
`res':
Pointer to an initialized matrix object, it will be resized if
needed.
`type':
Constant giving the type of the adjacency matrix to create for
undirected graphs. It is ignored for directed graphs. Possible
values:
`IGRAPH_GET_ADJACENCY_UPPER '
the upper right triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_LOWER '
the lower left triangle of the matrix is used.
`IGRAPH_GET_ADJACENCY_BOTH '
the whole matrix is used, a symmetric matrix is returned.
`type':
eids Logical, if true, then the edges ids plus one are stored in
the adjacency matrix, instead of the number of edges between the
two vertices. (The plus one is needed, since edge ids start from
zero, and zero means no edge in this case.)
*Returns:. *
`'
Error code: `IGRAPH_EINVAL' invalid type argument.
*See also:. *
`'
igraph_get_adjacency_sparse if you want a sparse matrix
representation
Time complexity: O(|V||V|), |V| is the number of vertices in the
graph.
File: igraph_reference_manual.info, Node: igraph_get_stochastic --- Stochastic adjacency matrix of a graph, Next: igraph_get_stochastic_sparsemat --- Stochastic adjacency matrix of a graph, Prev: igraph_get_adjacency --- Returns the adjacency matrix of a graph, Up: Other Operations
13.22.7 igraph_get_stochastic -- Stochastic adjacency matrix of a graph
-----------------------------------------------------------------------
int igraph_get_stochastic(const igraph_t *graph,
igraph_matrix_t *matrix,
igraph_bool_t column_wise);
Stochastic matrix of a graph. The stochastic matrix of a graph is
its adjacency matrix, normalized row-wise or column-wise, such that the
sum of each row (or column) is one.
*Arguments:. *
`graph':
The input graph.
`sparsemat':
Pointer to an initialized matrix, the result is stored here.
`column_wise':
Whether to normalize column-wise. For undirected graphs this
argument does not have any effect.
*Returns:. *
`'
Error code.
Time complexity: O(|V||V|), quadratic in the number of vertices.
*See also:. *
`'
igraph_get_stochastic_sparsemat(), the sparse version of this
function.
File: igraph_reference_manual.info, Node: igraph_get_stochastic_sparsemat --- Stochastic adjacency matrix of a graph, Next: igraph_get_edgelist --- Returns the list of edges in a graph, Prev: igraph_get_stochastic --- Stochastic adjacency matrix of a graph, Up: Other Operations
13.22.8 igraph_get_stochastic_sparsemat -- Stochastic adjacency matrix of a graph
---------------------------------------------------------------------------------
int igraph_get_stochastic_sparsemat(const igraph_t *graph,
igraph_sparsemat_t *sparsemat,
igraph_bool_t column_wise);
Stochastic matrix of a graph. The stochastic matrix of a graph is
its adjacency matrix, normalized row-wise or column-wise, such that the
sum of each row (or column) is one.
*Arguments:. *
`graph':
The input graph.
`sparsemat':
Pointer to an uninitialized sparse matrix, the result is stored
here.
`column_wise':
Whether to normalize column-wise. For undirected graphs this
argument does not have any effect.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
*See also:. *
`'
igraph_get_stochastic(), the dense version of this function.
File: igraph_reference_manual.info, Node: igraph_get_edgelist --- Returns the list of edges in a graph, Next: igraph_contract_vertices --- Replace multiple vertices with a single one_, Prev: igraph_get_stochastic_sparsemat --- Stochastic adjacency matrix of a graph, Up: Other Operations
13.22.9 igraph_get_edgelist -- Returns the list of edges in a graph
-------------------------------------------------------------------
int igraph_get_edgelist(const igraph_t *graph, igraph_vector_t *res, igraph_bool_t bycol);
The order of the edges is given by the edge ids.
*Arguments:. *
`graph':
Pointer to the graph object
`res':
Pointer to an initialized vector object, it will be resized.
`bycol':
Logical, if true, the edges will be returned columnwise, eg. the
first edge is ` res[0]->res[|E|]' , the second is `
res[1]->res[|E|+1]' , etc.
*Returns:. *
`'
Error code.
Time complexity: O(|E|), the number of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_contract_vertices --- Replace multiple vertices with a single one_, Prev: igraph_get_edgelist --- Returns the list of edges in a graph, Up: Other Operations
13.22.10 igraph_contract_vertices -- Replace multiple vertices with a single one.
---------------------------------------------------------------------------------
int igraph_contract_vertices(igraph_t *graph,
const igraph_vector_t *mapping,
const igraph_attribute_combination_t
*vertex_comb);
This function creates a new graph, by merging several vertices into
one. The vertices in the new graph correspond to sets of vertices in
the input graph.
*Arguments:. *
`graph':
The input graph, it can be directed or undirected.
`mapping':
A vector giving the mapping. For each vertex in the original
graph, it should contain its id in the new graph.
`vertex_comb':
What to do with the vertex attributes. See the igraph manual
section about attributes for details.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number or vertices plus
edges.
File: igraph_reference_manual.info, Node: Graph visitors, Next: Cliques and Independent Vertex Sets, Prev: Structural Properties of Graphs, Up: Top
14 Graph visitors
*****************
* Menu:
* Breadth-first search::
* Depth-first search::
File: igraph_reference_manual.info, Node: Breadth-first search, Next: Depth-first search, Up: Graph visitors
14.1 Breadth-first search
=========================
* Menu:
* igraph_bfs --- Breadth-first search::
* igraph_bfshandler_t --- Callback type for BFS function::
File: igraph_reference_manual.info, Node: igraph_bfs --- Breadth-first search, Next: igraph_bfshandler_t --- Callback type for BFS function, Up: Breadth-first search
14.1.1 igraph_bfs -- Breadth-first search
-----------------------------------------
int igraph_bfs(const igraph_t *graph,
igraph_integer_t root, const igraph_vector_t *roots,
igraph_neimode_t mode, igraph_bool_t unreachable,
const igraph_vector_t *restricted,
igraph_vector_t *order, igraph_vector_t *rank,
igraph_vector_t *father,
igraph_vector_t *pred, igraph_vector_t *succ,
igraph_vector_t *dist, igraph_bfshandler_t *callback,
void *extra);
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.
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.
*Arguments:. *
`graph':
The input graph.
`root':
The id of the root vertex. It is ignored if the `roots' argument
is not a null pointer.
`roots':
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.
`mode':
For directed graphs, it defines which edges to follow.
`IGRAPH_OUT' means following the direction of the edges,
`IGRAPH_IN' means the opposite, and `IGRAPH_ALL' ignores the
direction of the edges. This parameter is ignored for undirected
graphs.
`unreachable':
Logical scalar, 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.
`restricted':
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.
`order':
If not null pointer, then the vertex ids of the graph are stored
here, in the same order as they were visited.
`rank':
If not a null pointer, then the rank of each vertex is stored here.
`father':
If not a null pointer, then the id of the father of each vertex is
stored here.
`pred':
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.
`succ':
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.
`dist':
If not a null pointer, then the distance from the root of the
current search tree is stored here.
`callback':
If not null, then it should be a pointer to a function of type
`igraph_bfshandler_t' (*note igraph_bfshandler_t --- Callback type
for BFS function::). This function will be called, whenever a new
vertex is visited.
`extra':
Extra argument to pass to the callback function.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
* File examples/simple/igraph_bfs.c*
* File examples/simple/igraph_bfs2.c*
File: igraph_reference_manual.info, Node: igraph_bfshandler_t --- Callback type for BFS function, Prev: igraph_bfs --- Breadth-first search, Up: Breadth-first search
14.1.2 igraph_bfshandler_t -- Callback type for BFS function
------------------------------------------------------------
typedef igraph_bool_t igraph_bfshandler_t(const igraph_t *graph,
igraph_integer_t vid,
igraph_integer_t pred,
igraph_integer_t succ,
igraph_integer_t rank,
igraph_integer_t dist,
void *extra);
`igraph_bfs()' (*note igraph_bfs --- Breadth-first search::) 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
`igraph_bfshandler_t'. It has the following arguments:
*Arguments:. *
`graph':
The graph that that algorithm is working on. Of course this must
not be modified.
`vid':
The id of the vertex just found by the breadth-first search.
`pred':
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.
`succ':
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.
`rank':
The rank of the current vertex, it starts with zero.
`dist':
The distance (number of hops) of the current vertex from the root
of the current search tree.
`extra':
The extra argument that was passed to `igraph_bfs()' (*note
igraph_bfs --- Breadth-first search::).
*Returns:. *
`'
A logical value, if TRUE (=non-zero), that is interpreted as a
request to stop the BFS and return to the caller. If a BFS is
terminated like this, then all elements of the result vectors that
were not yet calculated at the point of the termination contain
`IGRAPH_NAN'.
*See also:. *
`'
`igraph_bfs()' (*note igraph_bfs --- Breadth-first search::)
File: igraph_reference_manual.info, Node: Depth-first search, Prev: Breadth-first search, Up: Graph visitors
14.2 Depth-first search
=======================
* Menu:
* igraph_dfs --- Depth-first search::
* igraph_dfshandler_t --- Callback type for the DFS function::
File: igraph_reference_manual.info, Node: igraph_dfs --- Depth-first search, Next: igraph_dfshandler_t --- Callback type for the DFS function, Up: Depth-first search
14.2.1 igraph_dfs -- Depth-first search
---------------------------------------
int igraph_dfs(const igraph_t *graph, igraph_integer_t root,
igraph_neimode_t mode, igraph_bool_t unreachable,
igraph_vector_t *order,
igraph_vector_t *order_out, igraph_vector_t *father,
igraph_vector_t *dist, igraph_dfshandler_t *in_callback,
igraph_dfshandler_t *out_callback,
void *extra);
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.
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.
*Arguments:. *
`graph':
The input graph.
`root':
The id of the root vertex.
`mode':
For directed graphs, it defines which edges to follow.
`IGRAPH_OUT' means following the direction of the edges,
`IGRAPH_IN' means the opposite, and `IGRAPH_ALL' ignores the
direction of the edges. This parameter is ignored for undirected
graphs.
`unreachable':
Logical scalar, 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.
`order':
If not null pointer, then the vertex ids of the graph are stored
here, in the same order as they were discovered.
`order_out':
If not a null pointer, then the vertex ids of the graphs are
stored here, in the order of the completion of their subtree.
`father':
If not a null pointer, then the id of the father of each vertex is
stored here.
`dist':
If not a null pointer, then the distance from the root of the
current search tree is stored here.
`in_callback':
If not null, then it should be a pointer to a function of type
`igraph_dfshandler_t' (*note igraph_dfshandler_t --- Callback type
for the DFS function::). This function will be called, whenever a
new vertex is discovered.
`out_callback':
If not null, then it should be a pointer to a function of type
`igraph_dfshandler_t' (*note igraph_dfshandler_t --- Callback type
for the DFS function::). This function will be called, whenever
the subtree of a vertex is completed.
`extra':
Extra argument to pass to the callback function(s).
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in the number of vertices and
edges.
File: igraph_reference_manual.info, Node: igraph_dfshandler_t --- Callback type for the DFS function, Prev: igraph_dfs --- Depth-first search, Up: Depth-first search
14.2.2 igraph_dfshandler_t -- Callback type for the DFS function
----------------------------------------------------------------
typedef igraph_bool_t igraph_dfshandler_t(const igraph_t *graph,
igraph_integer_t vid,
igraph_integer_t dist,
void *extra);
`igraph_dfs()' (*note igraph_dfs --- Depth-first search::) 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
`igraph_dfshandler_t'. They have the following arguments:
*Arguments:. *
`graph':
The graph that that algorithm is working on. Of course this must
not be modified.
`vid':
The id of the vertex just found by the depth-first search.
`dist':
The distance (number of hops) of the current vertex from the root
of the current search tree.
`extra':
The extra argument that was passed to `igraph_dfs()' (*note
igraph_dfs --- Depth-first search::).
*Returns:. *
`'
A logical value, if TRUE (=non-zero), that is interpreted as a
request to stop the DFS and return to the caller. If a DFS is
terminated like this, then all elements of the result vectors that
were not yet calculated at the point of the termination contain
`IGRAPH_NAN'.
*See also:. *
`'
`igraph_dfs()' (*note igraph_dfs --- Depth-first search::)
File: igraph_reference_manual.info, Node: Cliques and Independent Vertex Sets, Next: Graph Isomorphism, Prev: Graph visitors, Up: Top
15 Cliques and Independent Vertex Sets
**************************************
These functions calculate various graph properties related to cliques
and independent vertex sets.
* Menu:
* Cliques::
* Independent Vertex Sets::
File: igraph_reference_manual.info, Node: Cliques, Next: Independent Vertex Sets, Up: Cliques and Independent Vertex Sets
15.1 Cliques
============
* Menu:
* igraph_cliques --- Find all or some cliques in a graph::
* igraph_largest_cliques --- Finds the largest clique(s) in a graph.: igraph_largest_cliques --- Finds the largest clique[s] in a graph_.
* igraph_maximal_cliques --- Find all maximal cliques of a graph::
* igraph_maximal_cliques_count --- Count the number of maximal cliques in a graph::
* igraph_clique_number --- Find the clique number of the graph::
File: igraph_reference_manual.info, Node: igraph_cliques --- Find all or some cliques in a graph, Next: igraph_largest_cliques --- Finds the largest clique[s] in a graph_, Up: Cliques
15.1.1 igraph_cliques -- Find all or some cliques in a graph
------------------------------------------------------------
int igraph_cliques(const igraph_t *graph, igraph_vector_ptr_t *res,
igraph_integer_t min_size, igraph_integer_t max_size);
Cliques are fully connected subgraphs of a graph.
If you are only interested in the size of the largest clique in the
graph, use `igraph_clique_number()' (*note igraph_clique_number ---
Find the clique number of the graph::) instead.
The current implementation of this function searches for maximal
independent vertex sets (see `igraph_maximal_independent_vertex_sets()'
(*note igraph_maximal_independent_vertex_sets --- Find all maximal
independent vertex sets of a graph::)) in the complementer graph using
the algorithm published in: S. Tsukiyama, M. Ide, H. Ariyoshi and I.
Shirawaka. A new algorithm for generating all the maximal independent
sets. SIAM J Computing, 6:505-517, 1977.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_vector_t' objects which
contain the indices of vertices involved in a clique. The pointer
vector will be resized if needed but note that the objects in the
pointer vector will not be freed.
`min_size':
Integer giving the minimum size of the cliques to be returned. If
negative or zero, no lower bound will be used.
`max_size':
Integer giving the maximum size of the cliques to be returned. If
negative or zero, no upper bound will be used.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_largest_cliques()' (*note igraph_largest_cliques --- Finds
the largest clique[s] in a graph_::) and `igraph_clique_number()'
(*note igraph_clique_number --- Find the clique number of the
graph::).
Time complexity: TODO
* File examples/simple/igraph_cliques.c*
File: igraph_reference_manual.info, Node: igraph_largest_cliques --- Finds the largest clique[s] in a graph_, Next: igraph_maximal_cliques --- Find all maximal cliques of a graph, Prev: igraph_cliques --- Find all or some cliques in a graph, Up: Cliques
15.1.2 igraph_largest_cliques -- Finds the largest clique(s) in a graph.
------------------------------------------------------------------------
int igraph_largest_cliques(const igraph_t *graph, igraph_vector_ptr_t *res);
A clique is largest (quite intuitively) if there is no other clique
in the graph which contains more vertices.
Note that this is not necessarily the same as a maximal clique, ie.
the largest cliques are always maximal but a maximal clique is not
always largest.
The current implementation of this function searches for maximal
cliques using `igraph_maximal_cliques()' (*note igraph_maximal_cliques
--- Find all maximal cliques of a graph::) and drops those that are not
the largest.
The implementation of this function changed between igraph 0.5 and
0.6, so the order of the cliques and the order of vertices within the
cliques will almost surely be different between these two versions.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an initialized pointer vector, the result will be
stored here. It will be resized as needed. Note that vertices of a
clique may be returned in arbitrary order.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_cliques()' (*note igraph_cliques --- Find all or some
cliques in a graph::), `igraph_maximal_cliques()' (*note
igraph_maximal_cliques --- Find all maximal cliques of a graph::)
Time complexity: O(3^(|V|/3)) worst case.
File: igraph_reference_manual.info, Node: igraph_maximal_cliques --- Find all maximal cliques of a graph, Next: igraph_maximal_cliques_count --- Count the number of maximal cliques in a graph, Prev: igraph_largest_cliques --- Finds the largest clique[s] in a graph_, Up: Cliques
15.1.3 igraph_maximal_cliques -- Find all maximal cliques of a graph
--------------------------------------------------------------------
int igraph_maximal_cliques(const igraph_t *graph,
igraph_vector_ptr_t *res,
igraph_integer_t min_size,
igraph_integer_t max_size);
A maximal clique is a clique which can't be extended any more by
adding a new vertex to it.
If you are only interested in the size of the largest clique in the
graph, use `igraph_clique_number()' (*note igraph_clique_number ---
Find the clique number of the graph::) instead.
The current implementation uses a modified Bron-Kerbosch algorithm
to find the maximal cliques, see: David Eppstein, Maarten Lo"ffler,
Darren Strash: Listing All Maximal Cliques in Sparse Graphs in
Near-Optimal Time. Algorithms and Computation, Lecture Notes in
Computer Science Volume 6506, 2010, pp 403-414.
The implementation of this function changed between igraph 0.5 and
0.6 and also between 0.6 and 0.7, so the order of the cliques and the
order of vertices within the cliques will almost surely be different
between these three versions.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_vector_t' objects which
contain the indices of vertices involved in a clique. The pointer
vector will be resized if needed but note that the objects in the
pointer vector will not be freed. Note that vertices of a clique
may be returned in arbitrary order.
`min_size':
Integer giving the minimum size of the cliques to be returned. If
negative or zero, no lower bound will be used.
`max_size':
Integer giving the maximum size of the cliques to be returned. If
negative or zero, no upper bound will be used.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_maximal_independent_vertex_sets()' (*note
igraph_maximal_independent_vertex_sets --- Find all maximal
independent vertex sets of a graph::), `igraph_clique_number()'
(*note igraph_clique_number --- Find the clique number of the
graph::)
Time complexity: O(d(n-d)3^(d/3)) worst case, d is the degeneracy of
the graph, this is typically small for sparse graphs.
* File examples/simple/igraph_maximal_cliques.c*
File: igraph_reference_manual.info, Node: igraph_maximal_cliques_count --- Count the number of maximal cliques in a graph, Next: igraph_clique_number --- Find the clique number of the graph, Prev: igraph_maximal_cliques --- Find all maximal cliques of a graph, Up: Cliques
15.1.4 igraph_maximal_cliques_count -- Count the number of maximal cliques in a graph
-------------------------------------------------------------------------------------
int igraph_maximal_cliques_count(const igraph_t *graph,
igraph_integer_t *res,
igraph_integer_t min_size,
igraph_integer_t max_size);
The current implementation uses a modified Bron-Kerbosch algorithm
to find the maximal cliques, see: David Eppstein, Maarten Lo"ffler,
Darren Strash: Listing All Maximal Cliques in Sparse Graphs in
Near-Optimal Time. Algorithms and Computation, Lecture Notes in
Computer Science Volume 6506, 2010, pp 403-414.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_vector_t' objects which
contain the indices of vertices involved in a clique. The pointer
vector will be resized if needed but note that the objects in the
pointer vector will not be freed. Note that vertices of a clique
may be returned in arbitrary order.
`min_size':
Integer giving the minimum size of the cliques to be returned. If
negative or zero, no lower bound will be used.
`max_size':
Integer giving the maximum size of the cliques to be returned. If
negative or zero, no upper bound will be used.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_maximal_cliques()' (*note igraph_maximal_cliques --- Find
all maximal cliques of a graph::).
Time complexity: O(d(n-d)3^(d/3)) worst case, d is the degeneracy of
the graph, this is typically small for sparse graphs.
* File examples/simple/igraph_maximal_cliques.c*
File: igraph_reference_manual.info, Node: igraph_clique_number --- Find the clique number of the graph, Prev: igraph_maximal_cliques_count --- Count the number of maximal cliques in a graph, Up: Cliques
15.1.5 igraph_clique_number -- Find the clique number of the graph
------------------------------------------------------------------
int igraph_clique_number(const igraph_t *graph, igraph_integer_t *no);
The clique number of a graph is the size of the largest clique.
*Arguments:. *
`graph':
The input graph.
`no':
The clique number will be returned to the `igraph_integer_t'
pointed by this variable.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_cliques()' (*note igraph_cliques --- Find all or some
cliques in a graph::), `igraph_largest_cliques()' (*note
igraph_largest_cliques --- Finds the largest clique[s] in a
graph_::).
Time complexity: O(3^(|V|/3)) worst case.
File: igraph_reference_manual.info, Node: Independent Vertex Sets, Prev: Cliques, Up: Cliques and Independent Vertex Sets
15.2 Independent Vertex Sets
============================
* Menu:
* igraph_independent_vertex_sets --- Find all independent vertex sets in a graph::
* igraph_largest_independent_vertex_sets --- Finds the largest independent vertex set(s) in a graph.: igraph_largest_independent_vertex_sets --- Finds the largest independent vertex set[s] in a graph_.
* igraph_maximal_independent_vertex_sets --- Find all maximal independent vertex sets of a graph::
* igraph_independence_number --- Find the independence number of the graph::
File: igraph_reference_manual.info, Node: igraph_independent_vertex_sets --- Find all independent vertex sets in a graph, Next: igraph_largest_independent_vertex_sets --- Finds the largest independent vertex set[s] in a graph_, Up: Independent Vertex Sets
15.2.1 igraph_independent_vertex_sets -- Find all independent vertex sets in a graph
------------------------------------------------------------------------------------
int igraph_independent_vertex_sets(const igraph_t *graph,
igraph_vector_ptr_t *res,
igraph_integer_t min_size,
igraph_integer_t max_size);
A vertex set is considered independent if there are no edges between
them.
If you are interested in the size of the largest independent vertex
set, use `igraph_independence_number()' (*note
igraph_independence_number --- Find the independence number of the
graph::) instead.
The current implementation was ported to igraph from the Very Nauty
Graph Library by Keith Briggs and uses the algorithm from the paper S.
Tsukiyama, M. Ide, H. Ariyoshi and I. Shirawaka. A new algorithm for
generating all the maximal independent sets. SIAM J Computing,
6:505-517, 1977.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_vector_t' objects which
contain the indices of vertices involved in an independent vertex
set. The pointer vector will be resized if needed but note that the
objects in the pointer vector will not be freed.
`min_size':
Integer giving the minimum size of the sets to be returned. If
negative or zero, no lower bound will be used.
`max_size':
Integer giving the maximum size of the sets to be returned. If
negative or zero, no upper bound will be used.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_largest_independent_vertex_sets()' (*note
igraph_largest_independent_vertex_sets --- Finds the largest
independent vertex set[s] in a graph_::),
`igraph_independence_number()' (*note igraph_independence_number
--- Find the independence number of the graph::).
Time complexity: TODO
* File examples/simple/igraph_independent_sets.c*
File: igraph_reference_manual.info, Node: igraph_largest_independent_vertex_sets --- Finds the largest independent vertex set[s] in a graph_, Next: igraph_maximal_independent_vertex_sets --- Find all maximal independent vertex sets of a graph, Prev: igraph_independent_vertex_sets --- Find all independent vertex sets in a graph, Up: Independent Vertex Sets
15.2.2 igraph_largest_independent_vertex_sets -- Finds the largest independent vertex set(s) in a graph.
--------------------------------------------------------------------------------------------------------
int igraph_largest_independent_vertex_sets(const igraph_t *graph,
igraph_vector_ptr_t *res);
An independent vertex set is largest if there is no other
independent vertex set with more vertices in the graph.
The current implementation was ported to igraph from the Very Nauty
Graph Library by Keith Briggs and uses the algorithm from the paper S.
Tsukiyama, M. Ide, H. Ariyoshi and I. Shirawaka. A new algorithm for
generating all the maximal independent sets. SIAM J Computing,
6:505-517, 1977.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here. It
will be resized as needed.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_independent_vertex_sets()' (*note
igraph_independent_vertex_sets --- Find all independent vertex
sets in a graph::), `igraph_maximal_independent_vertex_sets()'
(*note igraph_maximal_independent_vertex_sets --- Find all maximal
independent vertex sets of a graph::).
Time complexity: TODO
File: igraph_reference_manual.info, Node: igraph_maximal_independent_vertex_sets --- Find all maximal independent vertex sets of a graph, Next: igraph_independence_number --- Find the independence number of the graph, Prev: igraph_largest_independent_vertex_sets --- Finds the largest independent vertex set[s] in a graph_, Up: Independent Vertex Sets
15.2.3 igraph_maximal_independent_vertex_sets -- Find all maximal independent vertex sets of a graph
----------------------------------------------------------------------------------------------------
int igraph_maximal_independent_vertex_sets(const igraph_t *graph,
igraph_vector_ptr_t *res);
A maximal independent vertex set is an independent vertex set which
can't be extended any more by adding a new vertex to it.
The algorithm used here is based on the following paper: S.
Tsukiyama, M. Ide, H. Ariyoshi and I. Shirawaka. A new algorithm for
generating all the maximal independent sets. SIAM J Computing,
6:505-517, 1977.
The implementation was originally written by Kevin O'Neill and
modified by K M Briggs in the Very Nauty Graph Library. I simply
re-wrote it to use igraph's data structures.
If you are interested in the size of the largest independent vertex
set, use `igraph_independence_number()' (*note
igraph_independence_number --- Find the independence number of the
graph::) instead.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to a pointer vector, the result will be stored here, ie.
`res' will contain pointers to `igraph_vector_t' objects which
contain the indices of vertices involved in an independent vertex
set. The pointer vector will be resized if needed but note that the
objects in the pointer vector will not be freed.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_maximal_cliques()' (*note igraph_maximal_cliques --- Find
all maximal cliques of a graph::), `igraph_independence_number()'
(*note igraph_independence_number --- Find the independence number
of the graph::)
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_independence_number --- Find the independence number of the graph, Prev: igraph_maximal_independent_vertex_sets --- Find all maximal independent vertex sets of a graph, Up: Independent Vertex Sets
15.2.4 igraph_independence_number -- Find the independence number of the graph
------------------------------------------------------------------------------
int igraph_independence_number(const igraph_t *graph, igraph_integer_t *no);
The independence number of a graph is the cardinality of the largest
independent vertex set.
The current implementation was ported to igraph from the Very Nauty
Graph Library by Keith Briggs and uses the algorithm from the paper S.
Tsukiyama, M. Ide, H. Ariyoshi and I. Shirawaka. A new algorithm for
generating all the maximal independent sets. SIAM J Computing,
6:505-517, 1977.
*Arguments:. *
`graph':
The input graph.
`no':
The independence number will be returned to the `igraph_integer_t'
pointed by this variable.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_independent_vertex_sets()' (*note
igraph_independent_vertex_sets --- Find all independent vertex
sets in a graph::).
Time complexity: TODO.
File: igraph_reference_manual.info, Node: Graph Isomorphism, Next: Graph Motifs; Dyad Census and Triad Census, Prev: Cliques and Independent Vertex Sets, Up: Top
16 Graph Isomorphism
********************
* Menu:
* The simple interface::
* The BLISS algorithm::
* The VF2 algorithm::
* The LAD algorithm::
* Functions for graphs with 3 or 4 vertices::
File: igraph_reference_manual.info, Node: The simple interface, Next: The BLISS algorithm, Up: Graph Isomorphism
16.1 The simple interface
=========================
igraph provides four set of functions to deal with graph isomorphism
problems.
The `igraph_isomorphic()' (*note igraph_isomorphic --- Decides
whether two graphs are isomorphic::) and `igraph_subisomorphic()'
(*note igraph_subisomorphic --- Decide subgraph isomorphism::)
functions make up the first set (in addition with the
`igraph_permute_vertices()' (*note igraph_permute_vertices --- Permute
the vertices::) function). These functions choose the algorithm which
is best for the supplied input graph. (The choice is not very
sophisticated though, see their documentation for details.)
The VF2 graph (and subgraph) isomorphism algorithm is implemented in
igraph, these functions are the second set. See
`igraph_isomorphic_vf2()' (*note igraph_isomorphic_vf2 --- Isomorphism
via VF2::) and `igraph_subisomorphic_vf2()' (*note
igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2::)
for starters.
Functions for the BLISS algorithm constitute the third set, see
`igraph_isomorphic_bliss()' (*note igraph_isomorphic_bliss --- Graph
isomorphism via BLISS::). This implementation only works for undirected
graphs.
Finally, the isomorphism classes of all graphs with three and four
vertices are precomputed and stored in igraph, so for these small
graphs there is a very simple fast way to decide isomorphism. See
`igraph_isomorphic_34()' (*note igraph_isomorphic_34 --- Graph
isomorphism for 3-4 vertices::).
* Menu:
* igraph_permute_vertices --- Permute the vertices::
* igraph_isomorphic --- Decides whether two graphs are isomorphic::
* igraph_subisomorphic --- Decide subgraph isomorphism::
File: igraph_reference_manual.info, Node: igraph_permute_vertices --- Permute the vertices, Next: igraph_isomorphic --- Decides whether two graphs are isomorphic, Up: The simple interface
16.1.1 igraph_permute_vertices -- Permute the vertices
------------------------------------------------------
int igraph_permute_vertices(const igraph_t *graph, igraph_t *res,
const igraph_vector_t *permutation);
This function creates a new graph from the input graph by permuting
its vertices according to the specified mapping. Call this function
with the output of `igraph_canonical_permutation()' (*note
igraph_canonical_permutation --- Canonical permutation using BLISS::)
to create the canonical form of a graph.
*Arguments:. *
`graph':
The input graph.
`res':
Pointer to an uninitialized graph object. The new graph is created
here.
`permutation':
The permutation to apply. Vertex 0 is mapped to the first element
of the vector, vertex 1 to the second, etc. Note that it is not
checked that the vector contains every element only once, and no
range checking is performed either.
*Returns:. *
`'
Error code.
Time complexity: O(|V|+|E|), linear in terms of the number of
vertices and edges.
File: igraph_reference_manual.info, Node: igraph_isomorphic --- Decides whether two graphs are isomorphic, Next: igraph_subisomorphic --- Decide subgraph isomorphism, Prev: igraph_permute_vertices --- Permute the vertices, Up: The simple interface
16.1.2 igraph_isomorphic -- Decides whether two graphs are isomorphic
---------------------------------------------------------------------
int igraph_isomorphic(const igraph_t *graph1, const igraph_t *graph2,
igraph_bool_t *iso);
From Wikipedia: The graph isomorphism problem or GI problem is the
graph theory problem of determining whether, given two graphs G1 and
G2, it is possible to permute (or relabel) the vertices of one graph so
that it is equal to the other. Such a permutation is called a graph
isomorphism.
This function decides which graph isomorphism algorithm to be used
based on the input graphs. Right now it does the following:
1. If one graph is directed and the other undirected then an error is
triggered.
2. If the two graphs does not have the same number of vertices and
edges it returns with `FALSE'.
3. Otherwise, if the graphs have three or four vertices then an O(1)
algorithm is used with precomputed data.
4. Otherwise, if the graphs are directed then VF2 is used, see
`igraph_isomorphic_vf2()' (*note igraph_isomorphic_vf2 ---
Isomorphism via VF2::).
5. Otherwise BLISS is used, see `igraph_isomorphic_bliss()' (*note
igraph_isomorphic_bliss --- Graph isomorphism via BLISS::).
Please call the VF2 and BLISS functions directly if you need
something more sophisticated, e.g. you need the isomorphic mapping.
*Arguments:. *
`graph1':
The first graph.
`graph2':
The second graph.
`iso':
Pointer to a logical variable, will be set to TRUE (1) if the two
graphs are isomorphic, and FALSE (0) otherwise.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_isoclass()' (*note igraph_isoclass --- Determine the
isomorphism class of a graph with 3 or 4 vertices::),
`igraph_isoclass_subgraph()' (*note igraph_isoclass_subgraph ---
The isomorphism class of a subgraph of a graph_::),
`igraph_isoclass_create()' (*note igraph_isoclass_create ---
Creates a graph from the given isomorphism class_::).
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_subisomorphic --- Decide subgraph isomorphism, Prev: igraph_isomorphic --- Decides whether two graphs are isomorphic, Up: The simple interface
16.1.3 igraph_subisomorphic -- Decide subgraph isomorphism
----------------------------------------------------------
int igraph_subisomorphic(const igraph_t *graph1, const igraph_t *graph2,
igraph_bool_t *iso);
Check whether `graph2' is isomorphic to a subgraph of `graph1'.
Currently this function just calls `igraph_subisomorphic_vf2()' (*note
igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2::)
for all graphs.
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected. This is
supposed to be the bigger graph.
`graph2':
The second input graph, it must have the same directedness as
`graph2', or an error is triggered. This is supposed to be the
smaller graph.
`iso':
Pointer to a boolean, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: The BLISS algorithm, Next: The VF2 algorithm, Prev: The simple interface, Up: Graph Isomorphism
16.2 The BLISS algorithm
========================
BLISS is a successor of the famous NAUTY algorithm and implementation.
While using the same ideas in general, with better heuristics and data
structure BLISS outperforms NAUTY on most graphs.
BLISS was developed and implemented by Tommi Junttila and Petteri
Kaski at Helsinki University of Technology, Finland. See Tommi
Juntilla's homepage at http://www.tcs.hut.fi/~tjunttil/
(http://www.tcs.hut.fi/~tjunttil/) and the publication at
http://www.siam.org/proceedings/alenex/2007/alx07_013junttilat.pdf
(http://www.siam.org/proceedings/alenex/2007/alx07_013junttilat.pdf)
for more information.
BLISS version 0.35 is included in igraph.
* Menu:
* igraph_bliss_sh_t --- Splitting heuristics for BLISS::
* igraph_bliss_info_t --- Information about a BLISS run::
* igraph_canonical_permutation --- Canonical permutation using BLISS::
* igraph_isomorphic_bliss --- Graph isomorphism via BLISS::
* igraph_automorphisms --- Number of automorphisms using BLISS::
File: igraph_reference_manual.info, Node: igraph_bliss_sh_t --- Splitting heuristics for BLISS, Next: igraph_bliss_info_t --- Information about a BLISS run, Up: The BLISS algorithm
16.2.1 igraph_bliss_sh_t -- Splitting heuristics for BLISS
----------------------------------------------------------
typedef enum { IGRAPH_BLISS_F=0, IGRAPH_BLISS_FL,
IGRAPH_BLISS_FS, IGRAPH_BLISS_FM,
IGRAPH_BLISS_FLM, IGRAPH_BLISS_FSM } igraph_bliss_sh_t;
*Values:. *
`IGRAPH_BLISS_F':
First non-singleton cell.
`IGRAPH_BLISS_FL':
First largest non-singleton cell.
`IGRAPH_BLISS_FS':
First smallest non-singleton cell.
`IGRAPH_BLISS_FM':
First maximally non-trivially connected non-singleton cell.
`IGRAPH_BLISS_FLM':
Largest maximally non-trivially connected non-singleton cell.
`IGRAPH_BLISS_FSM':
Smallest maximally non-trivially connected non-singletion cell.
File: igraph_reference_manual.info, Node: igraph_bliss_info_t --- Information about a BLISS run, Next: igraph_canonical_permutation --- Canonical permutation using BLISS, Prev: igraph_bliss_sh_t --- Splitting heuristics for BLISS, Up: The BLISS algorithm
16.2.2 igraph_bliss_info_t -- Information about a BLISS run
-----------------------------------------------------------
typedef struct igraph_bliss_info_t {
unsigned long nof_nodes;
unsigned long nof_leaf_nodes;
unsigned long nof_bad_nodes;
unsigned long nof_canupdates;
unsigned long max_level;
char *group_size;
} igraph_bliss_info_t;
Some secondary information found by the BLISS algorithm is stored
here. It is useful if you wany to study the internal working of the
algorithm.
*Values:. *
`nof_nodes':
The number of nodes in the search tree.
`nof_leaf_nodes':
The number of leaf nodes in the search tree.
`nof_bad_nodes':
Number of bad nodes.
`nof_canupdates':
Number of canrep updates.
`max_level':
Maximum level.
`group_size':
The size of the automorphism group of the graph, given as a
string. It should be deallocated via `free()' if not needed any
more.
See http://www.tcs.hut.fi/Software/bliss/index.html
(http://www.tcs.hut.fi/Software/bliss/index.html) for details about the
algorithm and these parameters.
File: igraph_reference_manual.info, Node: igraph_canonical_permutation --- Canonical permutation using BLISS, Next: igraph_isomorphic_bliss --- Graph isomorphism via BLISS, Prev: igraph_bliss_info_t --- Information about a BLISS run, Up: The BLISS algorithm
16.2.3 igraph_canonical_permutation -- Canonical permutation using BLISS
------------------------------------------------------------------------
int igraph_canonical_permutation(const igraph_t *graph, igraph_vector_t *labeling,
igraph_bliss_sh_t sh, igraph_bliss_info_t *info);
This function computes the canonical permutation which transforms
the graph into a canonical form by using the BLISS algorithm.
*Arguments:. *
`graph':
The input graph, it is treated as undirected and the multiple
edges are ignored.
`labeling':
Pointer to a vector, the result is stored here. The permutation
takes vertex 0 to the first element of the vector, vertex 1 to the
second, etc. The vector will be resized as needed.
`sh':
The split heuristics to be used in BLISS. See `igraph_bliss_sh_t'
(*note igraph_bliss_sh_t --- Splitting heuristics for BLISS::).
`info':
If not `NULL' then information on BLISS internals is stored here.
See `igraph_bliss_info_t' (*note igraph_bliss_info_t ---
Information about a BLISS run::).
*Returns:. *
`'
Error code.
Time complexity: exponential, in practice it is fast for many graphs.
File: igraph_reference_manual.info, Node: igraph_isomorphic_bliss --- Graph isomorphism via BLISS, Next: igraph_automorphisms --- Number of automorphisms using BLISS, Prev: igraph_canonical_permutation --- Canonical permutation using BLISS, Up: The BLISS algorithm
16.2.4 igraph_isomorphic_bliss -- Graph isomorphism via BLISS
-------------------------------------------------------------
int igraph_isomorphic_bliss(const igraph_t *graph1, const igraph_t *graph2,
igraph_bool_t *iso, igraph_vector_t *map12,
igraph_vector_t *map21,
igraph_bliss_sh_t sh1, igraph_bliss_sh_t sh2,
igraph_bliss_info_t *info1, igraph_bliss_info_t *info2);
This function uses the BLISS graph isomorphism algorithm, a
successor of the famous NAUTY algorithm and implementation. BLISS is
open source and licensed according to the GNU GPL. See
http://www.tcs.hut.fi/Software/bliss/index.html
(http://www.tcs.hut.fi/Software/bliss/index.html) for details.
Currently the 0.35 version of BLISS is included in igraph.
*Arguments:. *
`graph1':
The first input graph, it is assumed to be undirected, directed
graphs are treated as undirected too. The algorithm eliminates
multiple edges from the graph first.
`graph2':
The second input graph, it is assumed to be undirected, directed
graphs are treated as undirected too. The algorithm eliminates
multiple edges from the graph first.
`iso':
Pointer to a boolean, the result is stored here.
`map12':
A vector or `NULL' pointer. If not `NULL' then an isomorphic
mapping from `graph1' to `graph2' is stored here. If the input
graphs are not isomorphic then this vector is cleared, i.e. it
will have length zero.
`map21':
Similar to `map12', but for the mapping from `graph2' to `graph1'.
`sh1':
Splitting heuristics to be used for the first graph. See
`igraph_bliss_sh_t' (*note igraph_bliss_sh_t --- Splitting
heuristics for BLISS::).
`sh2':
Splitting heuristics to be used for the second graph. See
`igraph_bliss_sh_t' (*note igraph_bliss_sh_t --- Splitting
heuristics for BLISS::).
`info1':
If not `NULL', information about the canonization of the first
input graph is stored here. See `igraph_bliss_info_t' (*note
igraph_bliss_info_t --- Information about a BLISS run::) for
details. Note that if the two graphs have different number of
vertices or edges, then this is not filled.
`info2':
Same as `info1', but for the second graph.
*Returns:. *
`'
Error code.
Time complexity: exponential, but in practice it is quite fast.
File: igraph_reference_manual.info, Node: igraph_automorphisms --- Number of automorphisms using BLISS, Prev: igraph_isomorphic_bliss --- Graph isomorphism via BLISS, Up: The BLISS algorithm
16.2.5 igraph_automorphisms -- Number of automorphisms using BLISS
------------------------------------------------------------------
int igraph_automorphisms(const igraph_t *graph,
igraph_bliss_sh_t sh, igraph_bliss_info_t *info);
The number of automorphisms of a graph is computed using BLISS. The
result is returned as part of the `info' structure, in tag
`group_size'. It is returned as a string, as it can be very high even
for relatively small graphs. If the GNU MP library is used then this
number is exact, otherwise a `long double' is used and it is only
approximate. See also `igraph_bliss_info_t' (*note igraph_bliss_info_t
--- Information about a BLISS run::).
*Arguments:. *
`graph':
The input graph, it is treated as undirected and the multiple
edges are ignored.
`sh':
The split heuristics to be used in BLISS. See `igraph_bliss_sh_t'
(*note igraph_bliss_sh_t --- Splitting heuristics for BLISS::).
`info':
The result is stored here, in particular in the `group_size' tag
of `info'.
*Returns:. *
`'
Error code.
Time complexity: exponential, in practice it is fast for many graphs.
File: igraph_reference_manual.info, Node: The VF2 algorithm, Next: The LAD algorithm, Prev: The BLISS algorithm, Up: Graph Isomorphism
16.3 The VF2 algorithm
======================
* Menu:
* igraph_isomorphic_vf2 --- Isomorphism via VF2::
* igraph_count_isomorphisms_vf2 --- Number of isomorphisms via VF2::
* igraph_get_isomorphisms_vf2 --- Collect the isomorphic mappings::
* igraph_isohandler_t --- Callback type, called when an isomorphism was found: igraph_isohandler_t --- Callback type; called when an isomorphism was found.
* igraph_isocompat_t --- Callback type, called to check whether two vertices or edges are compatible: igraph_isocompat_t --- Callback type; called to check whether two vertices or edges are compatible.
* igraph_isomorphic_function_vf2 --- The generic VF2 interface::
* igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2::
* igraph_count_subisomorphisms_vf2 --- Number of subgraph isomorphisms using VF2::
* igraph_get_subisomorphisms_vf2 --- Return all subgraph isomorphic mappings::
* igraph_subisomorphic_function_vf2 --- Generic VF2 function for subgraph isomorphism problems::
File: igraph_reference_manual.info, Node: igraph_isomorphic_vf2 --- Isomorphism via VF2, Next: igraph_count_isomorphisms_vf2 --- Number of isomorphisms via VF2, Up: The VF2 algorithm
16.3.1 igraph_isomorphic_vf2 -- Isomorphism via VF2
---------------------------------------------------
int igraph_isomorphic_vf2(const igraph_t *graph1, const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_bool_t *iso, igraph_vector_t *map12,
igraph_vector_t *map21,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function performs the VF2 algorithm via calling
`igraph_isomorphic_function_vf2()' (*note
igraph_isomorphic_function_vf2 --- The generic VF2 interface::).
Note that this function cannot be used for deciding subgraph
isomorphism, use `igraph_subisomorphic_vf2()' (*note
igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2::)
for that.
*Arguments:. *
`graph1':
The first graph, may be directed or undirected.
`graph2':
The second graph. It must have the same directedness as `graph1',
otherwise an error is reported.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the isomorphism is calculated on the
colored graphs; i.e. two vertices can match only if their color
also matches. Supply a null pointer here if your graphs are not
colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`iso':
Pointer to a logical constant, the result of the algorithm will be
placed here.
`map12':
Pointer to an initialized vector or a NULL pointer. If not a NULL
pointer then the mapping from `graph1' to `graph2' is stored here.
If the graphs are not isomorphic then the vector is cleared (ie.
has zero elements).
`map21':
Pointer to an initialized vector or a NULL pointer. If not a NULL
pointer then the mapping from `graph2' to `graph1' is stored here.
If the graphs are not isomorphic then the vector is cleared (ie.
has zero elements).
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_subisomorphic_vf2()' (*note igraph_subisomorphic_vf2 ---
Decide subgraph isomorphism using VF2::),
`igraph_count_isomorphisms_vf2()' (*note
igraph_count_isomorphisms_vf2 --- Number of isomorphisms via
VF2::), `igraph_get_isomorphisms_vf2()' (*note
igraph_get_isomorphisms_vf2 --- Collect the isomorphic mappings::),
Time complexity: exponential, what did you expect?
* File examples/simple/igraph_isomorphic_vf2.c*
File: igraph_reference_manual.info, Node: igraph_count_isomorphisms_vf2 --- Number of isomorphisms via VF2, Next: igraph_get_isomorphisms_vf2 --- Collect the isomorphic mappings, Prev: igraph_isomorphic_vf2 --- Isomorphism via VF2, Up: The VF2 algorithm
16.3.2 igraph_count_isomorphisms_vf2 -- Number of isomorphisms via VF2
----------------------------------------------------------------------
int igraph_count_isomorphisms_vf2(const igraph_t *graph1, const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_integer_t *count,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function counts the number of isomorphic mappings between two
graphs. It uses the generic `igraph_isomorphic_function_vf2()' (*note
igraph_isomorphic_function_vf2 --- The generic VF2 interface::)
function.
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected.
`graph2':
The second input graph, it must have the same directedness as
`graph1', or an error will be reported.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the isomorphism is calculated on the
colored graphs; i.e. two vertices can match only if their color
also matches. Supply a null pointer here if your graphs are not
colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`count':
Point to an integer, the result will be stored here.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_get_isomorphisms_vf2 --- Collect the isomorphic mappings, Next: igraph_isohandler_t --- Callback type; called when an isomorphism was found, Prev: igraph_count_isomorphisms_vf2 --- Number of isomorphisms via VF2, Up: The VF2 algorithm
16.3.3 igraph_get_isomorphisms_vf2 -- Collect the isomorphic mappings
---------------------------------------------------------------------
int igraph_get_isomorphisms_vf2(const igraph_t *graph1,
const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_vector_ptr_t *maps,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function finds all the isomorphic mappings between two graphs.
It uses the `igraph_isomorphic_function_vf2()' (*note
igraph_isomorphic_function_vf2 --- The generic VF2 interface::)
function. Call the function with the same graph as `graph1' and
`graph2' to get automorphisms.
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected.
`graph2':
The second input graph, it must have the same directedness as
`graph1', or an error will be reported.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the isomorphism is calculated on the
colored graphs; i.e. two vertices can match only if their color
also matches. Supply a null pointer here if your graphs are not
colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`maps':
Pointer vector. On return it is empty if the input graphs are no
isomorphic. Otherwise it contains pointers to `igraph_vector_t'
objects, each vector is an isomorphic mapping of `graph2' to
`graph1'. Please note that you need to 1) Destroy the vectors via
`igraph_vector_destroy()' (*note igraph_vector_destroy ---
Destroys a vector object_::), 2) free them via `free()' and then
3) call `igraph_vector_ptr_destroy()' (*note
igraph_vector_ptr_destroy --- Destroys a pointer vector_::) on the
pointer vector to deallocate all memory when `maps' is no longer
needed.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_isohandler_t --- Callback type; called when an isomorphism was found, Next: igraph_isocompat_t --- Callback type; called to check whether two vertices or edges are compatible, Prev: igraph_get_isomorphisms_vf2 --- Collect the isomorphic mappings, Up: The VF2 algorithm
16.3.4 igraph_isohandler_t -- Callback type, called when an isomorphism was found
---------------------------------------------------------------------------------
typedef igraph_bool_t igraph_isohandler_t(const igraph_vector_t *map12,
const igraph_vector_t *map21, void *arg);
See the details at the documentation of
`igraph_isomorphic_function_vf2()' (*note
igraph_isomorphic_function_vf2 --- The generic VF2 interface::).
*Arguments:. *
`map12':
The mapping from the first graph to the second.
`map21':
The mapping from the second graph to the first, the inverse of
`map12' basically.
`arg':
This extra argument was passed to
`igraph_isomorphic_function_vf2()' (*note
igraph_isomorphic_function_vf2 --- The generic VF2 interface::)
when it was called.
*Returns:. *
`'
Boolean, whether to continue with the isomorphism search.
File: igraph_reference_manual.info, Node: igraph_isocompat_t --- Callback type; called to check whether two vertices or edges are compatible, Next: igraph_isomorphic_function_vf2 --- The generic VF2 interface, Prev: igraph_isohandler_t --- Callback type; called when an isomorphism was found, Up: The VF2 algorithm
16.3.5 igraph_isocompat_t -- Callback type, called to check whether two vertices or edges are compatible
--------------------------------------------------------------------------------------------------------
typedef igraph_bool_t igraph_isocompat_t(const igraph_t *graph1,
const igraph_t *graph2,
const igraph_integer_t g1_num,
const igraph_integer_t g2_num,
void *arg);
VF2 (subgraph) isomorphism functions can be restricted by defining
relations on the vertices and/or edges of the graphs, and then checking
whether the vertices (edges) match according to these relations.
This feature is implemented by two callbacks, one for vertices, one
for edges. Every time igraph tries to match a vertex (edge) of the
first (sub)graph to a vertex of the second graph, the vertex (edge)
compatibility callback is called. The callback returns a logical value,
giving whether the two vertices match.
Both callback functions are of type `igraph_isocompat_t'.
*Arguments:. *
`graph1':
The first graph.
`graph2':
The second graph.
`g1_num':
The id of a vertex or edge in the first graph.
`g2_num':
The id of a vertex or edge in the second graph.
`arg':
Extra argument to pass to the callback functions.
*Returns:. *
`'
Logical scalar, whether vertex (or edge) `g1_num' in `graph1' is
compatible with vertex (or edge) `g2_num' in `graph2'.
File: igraph_reference_manual.info, Node: igraph_isomorphic_function_vf2 --- The generic VF2 interface, Next: igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2, Prev: igraph_isocompat_t --- Callback type; called to check whether two vertices or edges are compatible, Up: The VF2 algorithm
16.3.6 igraph_isomorphic_function_vf2 -- The generic VF2 interface
------------------------------------------------------------------
int igraph_isomorphic_function_vf2(const igraph_t *graph1, const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_vector_t *map12,
igraph_vector_t *map21,
igraph_isohandler_t *isohandler_fn,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function is an implementation of the VF2 isomorphism algorithm,
see P. Foggia, C. Sansone, M. Vento, An Improved algorithm for matching
large graphs, Proc. of the 3rd IAPR-TC-15 International Workshop on
Graph-based Representations, Italy, 2001.
For using it you need to define a callback function of type
`igraph_isohandler_t' (*note igraph_isohandler_t --- Callback type;
called when an isomorphism was found::). This function will be called
whenever VF2 finds an isomorphism between the two graphs. The mapping
between the two graphs will be also provided to this function. If the
callback returns a nonzero value then the search is continued,
otherwise it stops.
*Arguments:. *
`graph1':
The first input graph.
`graph2':
The second input graph.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the isomorphism is calculated on the
colored graphs; i.e. two vertices can match only if their color
also matches. Supply a null pointer here if your graphs are not
colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`map12':
Pointer to an initialized vector or `NULL'. If not `NULL' and the
supplied graphs are isomorphic then the permutation taking
`graph1' to `graph' is stored here. If not `NULL' and the graphs
are not isomorphic then a zero-length vector is returned.
`map21':
This is the same as `map12', but for the permutation taking
`graph2' to `graph1'.
`isohandler_fn':
The callback function to be called if an isomorphism is found. See
also `igraph_isohandler_t' (*note igraph_isohandler_t --- Callback
type; called when an isomorphism was found::).
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `isohandler_fn',
`node_compat_fn' and `edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2, Next: igraph_count_subisomorphisms_vf2 --- Number of subgraph isomorphisms using VF2, Prev: igraph_isomorphic_function_vf2 --- The generic VF2 interface, Up: The VF2 algorithm
16.3.7 igraph_subisomorphic_vf2 -- Decide subgraph isomorphism using VF2
------------------------------------------------------------------------
int igraph_subisomorphic_vf2(const igraph_t *graph1, const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_bool_t *iso, igraph_vector_t *map12,
igraph_vector_t *map21,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
Decides whether a subgraph of `graph1' is isomorphic to `graph2'. It
uses `igraph_subisomorphic_function_vf2()' (*note
igraph_subisomorphic_function_vf2 --- Generic VF2 function for subgraph
isomorphism problems::).
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected. This is
supposed to be the larger graph.
`graph2':
The second input graph, it must have the same directedness as
`graph1'. This is supposed to be the smaller graph.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the subgraph isomorphism is calculated
on the colored graphs; i.e. two vertices can match only if their
color also matches. Supply a null pointer here if your graphs are
not colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`iso':
Pointer to a boolean. The result of the decision problem is stored
here.
`map12':
Pointer to a vector or `NULL'. If not `NULL', then an isomorphic
mapping from `graph1' to `graph2' is stored here.
`map21':
Pointer to a vector ot `NULL'. If not `NULL', then an isomorphic
mapping from `graph2' to `graph1' is stored here.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_count_subisomorphisms_vf2 --- Number of subgraph isomorphisms using VF2, Next: igraph_get_subisomorphisms_vf2 --- Return all subgraph isomorphic mappings, Prev: igraph_subisomorphic_vf2 --- Decide subgraph isomorphism using VF2, Up: The VF2 algorithm
16.3.8 igraph_count_subisomorphisms_vf2 -- Number of subgraph isomorphisms using VF2
------------------------------------------------------------------------------------
int igraph_count_subisomorphisms_vf2(const igraph_t *graph1, const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_integer_t *count,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
Count the number of isomorphisms between subgraphs of `graph1' and
`graph2'. This function uses `igraph_subisomorphic_function_vf2()'
(*note igraph_subisomorphic_function_vf2 --- Generic VF2 function for
subgraph isomorphism problems::).
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected. This is
supposed to be the larger graph.
`graph2':
The second input graph, it must have the same directedness as
`graph1'. This is supposed to be the smaller graph.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the subgraph isomorphism is calculated
on the colored graphs; i.e. two vertices can match only if their
color also matches. Supply a null pointer here if your graphs are
not colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`count':
Pointer to an integer. The number of subgraph isomorphisms is
stored here.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_get_subisomorphisms_vf2 --- Return all subgraph isomorphic mappings, Next: igraph_subisomorphic_function_vf2 --- Generic VF2 function for subgraph isomorphism problems, Prev: igraph_count_subisomorphisms_vf2 --- Number of subgraph isomorphisms using VF2, Up: The VF2 algorithm
16.3.9 igraph_get_subisomorphisms_vf2 -- Return all subgraph isomorphic mappings
--------------------------------------------------------------------------------
int igraph_get_subisomorphisms_vf2(const igraph_t *graph1,
const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_vector_ptr_t *maps,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function collects all isomorphic mappings of `graph2' to a
subgraph of `graph1'. It uses the `igraph_subisomorphic_function_vf2()'
(*note igraph_subisomorphic_function_vf2 --- Generic VF2 function for
subgraph isomorphism problems::) function.
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected. This is
supposed to be the larger graph.
`graph2':
The second input graph, it must have the same directedness as
`graph1'. This is supposed to be the smaller graph.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the subgraph isomorphism is calculated
on the colored graphs; i.e. two vertices can match only if their
color also matches. Supply a null pointer here if your graphs are
not colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`maps':
Pointer vector. On return it contains pointers to
`igraph_vector_t' objects, each vector is an isomorphic mapping of
`graph2' to a subgraph of `graph1'. Please note that you need to
1) Destroy the vectors via `igraph_vector_destroy()' (*note
igraph_vector_destroy --- Destroys a vector object_::), 2) free
them via `free()' and then 3) call `igraph_vector_ptr_destroy()'
(*note igraph_vector_ptr_destroy --- Destroys a pointer vector_::)
on the pointer vector to deallocate all memory when `maps' is no
longer needed.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `node_compat_fn' and
`edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: igraph_subisomorphic_function_vf2 --- Generic VF2 function for subgraph isomorphism problems, Prev: igraph_get_subisomorphisms_vf2 --- Return all subgraph isomorphic mappings, Up: The VF2 algorithm
16.3.10 igraph_subisomorphic_function_vf2 -- Generic VF2 function for subgraph isomorphism problems
---------------------------------------------------------------------------------------------------
int igraph_subisomorphic_function_vf2(const igraph_t *graph1,
const igraph_t *graph2,
const igraph_vector_int_t *vertex_color1,
const igraph_vector_int_t *vertex_color2,
const igraph_vector_int_t *edge_color1,
const igraph_vector_int_t *edge_color2,
igraph_vector_t *map12,
igraph_vector_t *map21,
igraph_isohandler_t *isohandler_fn,
igraph_isocompat_t *node_compat_fn,
igraph_isocompat_t *edge_compat_fn,
void *arg);
This function is the pair of `igraph_isomorphic_function_vf2()'
(*note igraph_isomorphic_function_vf2 --- The generic VF2 interface::),
for subgraph isomorphism problems. It searches for subgraphs of
`graph1' which are isomorphic to `graph2'. When it founds an isomorphic
mapping it calls the supplied callback `isohandler_fn'. The mapping
(and its inverse) and the additional `arg' argument are supplied to the
callback.
*Arguments:. *
`graph1':
The first input graph, may be directed or undirected. This is
supposed to be the larger graph.
`graph2':
The second input graph, it must have the same directedness as
`graph1'. This is supposed to be the smaller graph.
`vertex_color1':
An optional color vector for the first graph. If color vectors are
given for both graphs, then the subgraph isomorphism is calculated
on the colored graphs; i.e. two vertices can match only if their
color also matches. Supply a null pointer here if your graphs are
not colored.
`vertex_color2':
An optional color vector for the second graph. See the previous
argument for explanation.
`edge_color1':
An optional edge color vector for the first graph. The matching
edges in the two graphs must have matching colors as well. Supply
a null pointer here if your graphs are not edge-colored.
`edge_color2':
The edge color vector for the second graph.
`map12':
Pointer to a vector or `NULL'. If not `NULL', then an isomorphic
mapping from `graph1' to `graph2' is stored here.
`map21':
Pointer to a vector ot `NULL'. If not `NULL', then an isomorphic
mapping from `graph2' to `graph1' is stored here.
`isohandler_fn':
A pointer to a function of type `igraph_isohandler_t' (*note
igraph_isohandler_t --- Callback type; called when an isomorphism
was found::). This will be called whenever a subgraph isomorphism
is found. If the function returns with a non-zero value then the
search is continued, otherwise it stops and the function returns.
`node_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two nodes are compatible.
`edge_compat_fn':
A pointer to a function of type `igraph_isocompat_t' (*note
igraph_isocompat_t --- Callback type; called to check whether two
vertices or edges are compatible::). This function will be called
by the algorithm to determine whether two edges are compatible.
`arg':
Extra argument to supply to functions `isohandler_fn',
`node_compat_fn' and `edge_compat_fn'.
*Returns:. *
`'
Error code.
Time complexity: exponential.
File: igraph_reference_manual.info, Node: The LAD algorithm, Next: Functions for graphs with 3 or 4 vertices, Prev: The VF2 algorithm, Up: Graph Isomorphism
16.4 The LAD algorithm
======================
* Menu:
* igraph_subisomorphic_lad --- Check subgraph isomorphism with the LAD algorithm::
File: igraph_reference_manual.info, Node: igraph_subisomorphic_lad --- Check subgraph isomorphism with the LAD algorithm, Up: The LAD algorithm
16.4.1 igraph_subisomorphic_lad -- Check subgraph isomorphism with the LAD algorithm
------------------------------------------------------------------------------------
int igraph_subisomorphic_lad(const igraph_t *pattern, const igraph_t *target,
igraph_vector_ptr_t *domains,
igraph_bool_t *iso, igraph_vector_t *map,
igraph_vector_ptr_t *maps,
igraph_bool_t induced, int time_limit);
Check whether `pattern' is isomorphic to a subgraph os `target'.
The original LAD implementation by Christine Solnon was used as the
basis of this code.
See more about at http://liris.cnrs.fr/csolnon/LAD.html
(http://liris.cnrs.fr/csolnon/LAD.html) and in Christine Solnon:
AllDifferent-based Filtering for Subgraph Isomorphism. Artificial
Intelligence, 174(12-13):850-864, August 2010, Elsevier
*Arguments:. *
`pattern':
The smaller graph, it can be directed or undirected.
`target':
The bigger graph, it can be directed or undirected.
`domains':
A pointer vector, or a null pointer. If a pointer vector, then it
must contain pointers to `igraph_vector_t' objects and the length
of the vector must match the number of vertices in the `pattern'
graph. For each vertex, the ids of the compatible vertices in the
target graph are listed.
`iso':
Pointer to a boolean, or a null pointer. If not a null pointer,
then the boolean is set to TRUE (1) if a subgraph isomorphism is
found, and to FALSE (0) otherwise.
`map':
Pointer to a vector or a null pointer. If not a null pointer and a
subgraph isomorphism is found, the matching vertices from the
target graph are listed here, for each vertex (in vertex id order)
from the pattern graph.
`maps':
Pointer vector or a null pointer. If not a null pointer, then all
subgraph isomorphisms are stored in the pointer vector, in
`igraph_vector_t' objects.
`induced':
Boolean, whether to search for induced matching subgraphs.
`time_limit':
Processor time limit in seconds. Supply zero here for no limit. If
the time limit is over, then the function signals an error.
*Returns:. *
`'
Error code
*See also:. *
`'
`igraph_subisomorphic_vf2()' (*note igraph_subisomorphic_vf2 ---
Decide subgraph isomorphism using VF2::) for the VF2 algorithm.
Time complexity: exponential.
* File examples/simple/igraph_subisomorphic_lad.c*
File: igraph_reference_manual.info, Node: Functions for graphs with 3 or 4 vertices, Prev: The LAD algorithm, Up: Graph Isomorphism
16.5 Functions for graphs with 3 or 4 vertices
==============================================
* Menu:
* igraph_isomorphic_34 --- Graph isomorphism for 3-4 vertices::
* igraph_isoclass --- Determine the isomorphism class of a graph with 3 or 4 vertices::
* igraph_isoclass_subgraph --- The isomorphism class of a subgraph of a graph.: igraph_isoclass_subgraph --- The isomorphism class of a subgraph of a graph_.
* igraph_isoclass_create --- Creates a graph from the given isomorphism class.: igraph_isoclass_create --- Creates a graph from the given isomorphism class_.
File: igraph_reference_manual.info, Node: igraph_isomorphic_34 --- Graph isomorphism for 3-4 vertices, Next: igraph_isoclass --- Determine the isomorphism class of a graph with 3 or 4 vertices, Up: Functions for graphs with 3 or 4 vertices
16.5.1 igraph_isomorphic_34 -- Graph isomorphism for 3-4 vertices
-----------------------------------------------------------------
int igraph_isomorphic_34(const igraph_t *graph1, const igraph_t *graph2,
igraph_bool_t *iso);
This function uses precomputed indices to decide isomorphism
problems for graphs with only 3 or 4 vertices.
*Arguments:. *
`graph1':
The first input graph.
`graph2':
The second input graph. Must have the same directedness as
`graph1'.
`iso':
Pointer to a boolean, the result is stored here.
*Returns:. *
`'
Error code.
Time complexity: O(1).
File: igraph_reference_manual.info, Node: igraph_isoclass --- Determine the isomorphism class of a graph with 3 or 4 vertices, Next: igraph_isoclass_subgraph --- The isomorphism class of a subgraph of a graph_, Prev: igraph_isomorphic_34 --- Graph isomorphism for 3-4 vertices, Up: Functions for graphs with 3 or 4 vertices
16.5.2 igraph_isoclass -- Determine the isomorphism class of a graph with 3 or 4 vertices
-----------------------------------------------------------------------------------------
int igraph_isoclass(const igraph_t *graph, igraph_integer_t *isoclass);
All graphs with a given number of vertices belong to a number of
isomorphism classes, with every graph in a given class being isomorphic
to each other.
This function gives the isomorphism class (a number) of a graph. Two
graphs have the same isomorphism class if and only if they are
isomorphic.
The first isomorphism class is numbered zero and it is the empty
graph, the last isomorphism class is the full graph. The number of
isomorphism class for directed graphs with three vertices is 16
(between 0 and 15), for undirected graph it is only 4. For graphs with
four vertices it is 218 (directed) and 11 (undirected).
*Arguments:. *
`graph':
The graph object.
`isoclass':
Pointer to an integer, the isomorphism class will be stored here.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_isomorphic()' (*note igraph_isomorphic --- Decides whether
two graphs are isomorphic::), `igraph_isoclass_subgraph()' (*note
igraph_isoclass_subgraph --- The isomorphism class of a subgraph
of a graph_::), `igraph_isoclass_create()' (*note
igraph_isoclass_create --- Creates a graph from the given
isomorphism class_::), `igraph_motifs_randesu()' (*note
igraph_motifs_randesu --- Count the number of motifs in a graph::).
Because of some limitations this function works only for graphs with
three of four vertices.
Time complexity: O(|E|), the number of edges in the graph.
File: igraph_reference_manual.info, Node: igraph_isoclass_subgraph --- The isomorphism class of a subgraph of a graph_, Next: igraph_isoclass_create --- Creates a graph from the given isomorphism class_, Prev: igraph_isoclass --- Determine the isomorphism class of a graph with 3 or 4 vertices, Up: Functions for graphs with 3 or 4 vertices
16.5.3 igraph_isoclass_subgraph -- The isomorphism class of a subgraph of a graph.
----------------------------------------------------------------------------------
int igraph_isoclass_subgraph(const igraph_t *graph, igraph_vector_t *vids,
igraph_integer_t *isoclass);
This function is only implemented for subgraphs with three or four
vertices.
*Arguments:. *
`graph':
The graph object.
`vids':
A vector containing the vertex ids to be considered as a subgraph.
Each vertex id should be included at most once.
`isoclass':
Pointer to an integer, this will be set to the isomorphism class.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_isoclass()' (*note igraph_isoclass --- Determine the
isomorphism class of a graph with 3 or 4 vertices::),
`igraph_isomorphic()' (*note igraph_isomorphic --- Decides whether
two graphs are isomorphic::), `igraph_isoclass_create()' (*note
igraph_isoclass_create --- Creates a graph from the given
isomorphism class_::).
Time complexity: O((d+n)*n), d is the average degree in the network,
and n is the number of vertices in `vids'.
File: igraph_reference_manual.info, Node: igraph_isoclass_create --- Creates a graph from the given isomorphism class_, Prev: igraph_isoclass_subgraph --- The isomorphism class of a subgraph of a graph_, Up: Functions for graphs with 3 or 4 vertices
16.5.4 igraph_isoclass_create -- Creates a graph from the given isomorphism class.
----------------------------------------------------------------------------------
int igraph_isoclass_create(igraph_t *graph, igraph_integer_t size,
igraph_integer_t number, igraph_bool_t directed);
This function is implemented only for graphs with three or four
vertices.
*Arguments:. *
`graph':
Pointer to an uninitialized graph object.
`size':
The number of vertices to add to the graph.
`number':
The isomorphism class.
`directed':
Logical constant, whether to create a directed graph.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_isoclass()' (*note igraph_isoclass --- Determine the
isomorphism class of a graph with 3 or 4 vertices::),
`igraph_isoclass_subgraph()' (*note igraph_isoclass_subgraph ---
The isomorphism class of a subgraph of a graph_::),
`igraph_isomorphic()' (*note igraph_isomorphic --- Decides whether
two graphs are isomorphic::).
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges in the graph to create.
File: igraph_reference_manual.info, Node: Graph Motifs; Dyad Census and Triad Census, Next: Generating Layouts for Graph Drawing, Prev: Graph Isomorphism, Up: Top
17 Graph Motifs, Dyad Census and Triad Census
*********************************************
This section deals with functions which find small induced subgraphs in
a graph. These were first defined for subgraphs of two and three
vertices by Holland and Leinhardt, and named dyad census and triad
census.
* Menu:
* igraph_dyad_census --- Calculating the dyad census as defined by Holland and Leinhardt::
* igraph_triad_census --- Triad census, as defined by Davis and Leinhardt: igraph_triad_census --- Triad census; as defined by Davis and Leinhardt.
* Graph motifs::
File: igraph_reference_manual.info, Node: igraph_dyad_census --- Calculating the dyad census as defined by Holland and Leinhardt, Next: igraph_triad_census --- Triad census; as defined by Davis and Leinhardt, Up: Graph Motifs; Dyad Census and Triad Census
17.1 igraph_dyad_census -- Calculating the dyad census as defined by Holland and Leinhardt
==========================================================================================
int igraph_dyad_census(const igraph_t *graph, igraph_integer_t *mut,
igraph_integer_t *asym, igraph_integer_t *null);
Dyad census means classifying each pair of vertices of a directed
graph into three categories: mutual, there is an edge from `a' to `b'
and also from `b' to `a'; asymmetric, there is an edge either from `a'
to `b' or from `b' to `a' but not the other way and null, no edges
between `a' and `b'.
Holland, P.W. and Leinhardt, S. (1970). A Method for Detecting
Structure in Sociometric Data. American Journal of Sociology, 70,
492-513.
*Arguments:. *
`graph':
The input graph, a warning is given if undirected as the results
are undefined for undirected graphs.
`mut':
Pointer to an integer, the number of mutual dyads is stored here.
`asym':
Pointer to an integer, the number of asymmetric dyads is stored
here.
`null':
Pointer to an integer, the number of null dyads is stored here.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_reciprocity()' (*note igraph_reciprocity --- Calculates
the reciprocity of a directed graph_::), `igraph_triad_census()'
(*note igraph_triad_census --- Triad census; as defined by Davis
and Leinhardt::).
Time complexity: O(|V|+|E|), the number of vertices plus the number
of edges.
File: igraph_reference_manual.info, Node: igraph_triad_census --- Triad census; as defined by Davis and Leinhardt, Next: Graph motifs, Prev: igraph_dyad_census --- Calculating the dyad census as defined by Holland and Leinhardt, Up: Graph Motifs; Dyad Census and Triad Census
17.2 igraph_triad_census -- Triad census, as defined by Davis and Leinhardt
===========================================================================
int igraph_triad_census(const igraph_t *graph, igraph_vector_t *res);
Calculating the triad census means classifying every triple of
vertices in a directed graph. A triple can be in one of 16 states:
`003 '
A, B, C, the empty graph.
`012 '
A->B, C, a graph with a single directed edge.
`102 '
A<->B, C, a graph with a mutual connection between two vertices.
`021D '
A<-B->C, the binary out-tree.
`021U '
A->B<-C, the binary in-tree.
`021C '
A->B->C, the directed line.
`111D '
A<->B<-C.
`111U '
A<->B->C.
`030T '
A->B<-C, A->C.
`030C '
A<-B<-C, A->C.
`201 '
A<->B<->C.
`120D '
A<-B->C, A<->C.
`120U '
A->B<-C, A<->C.
`120C '
A->B->C, A<->C.
`210 '
A->B<->C, A<->C.
`300 '
A<->B<->C, A<->C, the complete graph.
See also Davis, J.A. and Leinhardt, S. (1972). The Structure of
Positive Interpersonal Relations in Small Groups. In J. Berger (Ed.),
Sociological Theories in Progress, Volume 2, 218-251. Boston: Houghton
Mifflin.
This function calls `igraph_motifs_randesu()' (*note
igraph_motifs_randesu --- Count the number of motifs in a graph::)
which is an implementation of the FANMOD motif finder tool, see
`igraph_motifs_randesu()' (*note igraph_motifs_randesu --- Count the
number of motifs in a graph::) for details. Note that the order of the
triads is not the same for `igraph_triad_census()' (*note
igraph_triad_census --- Triad census; as defined by Davis and
Leinhardt::) and `igraph_motifs_randesu()' (*note igraph_motifs_randesu
--- Count the number of motifs in a graph::).
*Arguments:. *
`graph':
The input graph. A warning is given for undirected graphs, as the
result is undefined for those.
`res':
Pointer to an initialized vector, the result is stored here in the
same order as given in the list above. Note that this order is
different than the one used by `igraph_motifs_randesu()' (*note
igraph_motifs_randesu --- Count the number of motifs in a graph::).
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_motifs_randesu()' (*note igraph_motifs_randesu --- Count
the number of motifs in a graph::), `igraph_dyad_census()' (*note
igraph_dyad_census --- Calculating the dyad census as defined by
Holland and Leinhardt::).
Time complexity: TODO.
File: igraph_reference_manual.info, Node: Graph motifs, Prev: igraph_triad_census --- Triad census; as defined by Davis and Leinhardt, Up: Graph Motifs; Dyad Census and Triad Census
17.3 Graph motifs
=================
* Menu:
* igraph_motifs_randesu --- Count the number of motifs in a graph::
* igraph_motifs_randesu_no --- Count the total number of motifs in a graph::
* igraph_motifs_randesu_estimate --- Estimate the total number of motifs in a graph::
* igraph_motifs_randesu_callback --- Finds motifs in a graph and calls a function for each of them::
* igraph_motifs_handler_t --- Callback type for igraph_motifs_randesu_callback::
File: igraph_reference_manual.info, Node: igraph_motifs_randesu --- Count the number of motifs in a graph, Next: igraph_motifs_randesu_no --- Count the total number of motifs in a graph, Up: Graph motifs
17.3.1 igraph_motifs_randesu -- Count the number of motifs in a graph
---------------------------------------------------------------------
int igraph_motifs_randesu(const igraph_t *graph, igraph_vector_t *hist,
int size, const igraph_vector_t *cut_prob);
Motifs are small connected subgraphs of a given structure in a
graph. It is argued that the motif profile (ie. the number of different
motifs in the graph) is characteristic for different types of networks
and network function is related to the motifs in the graph.
This function is able to find the different motifs of size three and
four (ie. the number of different subgraphs with three and four
vertices) in the network.
In a big network the total number of motifs can be very large, so it
takes a lot of time to find all of them, a sampling method can be used.
This function is capable of doing sampling via the `cut_prob' argument.
This argument gives the probability that a branch of the motif search
tree will not be explored. See S. Wernicke and F. Rasche: FANMOD: a
tool for fast network motif detection, Bioinformatics 22(9), 1152-1153,
2006 for details.
Set the `cut_prob' argument to a zero vector for finding all motifs.
Directed motifs will be counted in directed graphs and undirected
motifs in undirected graphs.
*Arguments:. *
`graph':
The graph to find the motifs in.
`hist':
The result of the computation, it gives the number of motifs found
for each isomorphism class. See `igraph_isoclass()' (*note
igraph_isoclass --- Determine the isomorphism class of a graph
with 3 or 4 vertices::) for help about isomorphism classes. Note
that this function does _not_ count isomorphism classes that are
not connected and will report NaN (more precisely `IGRAPH_NAN')
for them.
`size':
The size of the motifs to search for. Only three and four are
implemented currently. The limitation is not in the motif finding
code, but the graph isomorphism code.
`cut_prob':
Vector of probabilities for cutting the search tree at a given
level. The first element is the first level, etc. Supply all
zeros here (of length `size') to find all motifs in a graph.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_motifs_randesu_estimate()' (*note
igraph_motifs_randesu_estimate --- Estimate the total number of
motifs in a graph::) for estimating the number of motifs in a
graph, this can help to set the `cut_prob' parameter;
`igraph_motifs_randesu_no()' (*note igraph_motifs_randesu_no ---
Count the total number of motifs in a graph::) to calculate the
total number of motifs of a given size in a graph;
`igraph_motifs_randesu_callback()' (*note
igraph_motifs_randesu_callback --- Finds motifs in a graph and
calls a function for each of them::) for calling a callback
function for every motif found.
Time complexity: TODO.
* File examples/simple/igraph_motifs_randesu.c*
File: igraph_reference_manual.info, Node: igraph_motifs_randesu_no --- Count the total number of motifs in a graph, Next: igraph_motifs_randesu_estimate --- Estimate the total number of motifs in a graph, Prev: igraph_motifs_randesu --- Count the number of motifs in a graph, Up: Graph motifs
17.3.2 igraph_motifs_randesu_no -- Count the total number of motifs in a graph
------------------------------------------------------------------------------
int igraph_motifs_randesu_no(const igraph_t *graph, igraph_integer_t *no,
int size, const igraph_vector_t *cut_prob);
This function counts the total number of motifs in a graph without
assigning isomorphism classes to them.
Directed motifs will be counted in directed graphs and undirected
motifs in undirected graphs.
*Arguments:. *
`graph':
The graph object to study.
`no':
Pointer to an integer type, the result will be stored here.
`size':
The size of the motifs to count.
`cut_prob':
Vector giving the probabilities that a branch of the search tree
will be cut at a given level.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_motifs_randesu()' (*note igraph_motifs_randesu --- Count
the number of motifs in a graph::),
`igraph_motifs_randesu_estimate()' (*note
igraph_motifs_randesu_estimate --- Estimate the total number of
motifs in a graph::).
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_motifs_randesu_estimate --- Estimate the total number of motifs in a graph, Next: igraph_motifs_randesu_callback --- Finds motifs in a graph and calls a function for each of them, Prev: igraph_motifs_randesu_no --- Count the total number of motifs in a graph, Up: Graph motifs
17.3.3 igraph_motifs_randesu_estimate -- Estimate the total number of motifs in a graph
---------------------------------------------------------------------------------------
int igraph_motifs_randesu_estimate(const igraph_t *graph, igraph_integer_t *est,
int size, const igraph_vector_t *cut_prob,
igraph_integer_t sample_size,
const igraph_vector_t *parsample);
This function is useful for large graphs for which it is not
feasible to count all the different motifs, because there is very many
of them.
The total number of motifs is estimated by taking a sample of
vertices and counts all motifs in which these vertices are included.
(There is also a `cut_prob' parameter which gives the probabilities to
cut a branch of the search tree.)
Directed motifs will be counted in directed graphs and undirected
motifs in undirected graphs.
*Arguments:. *
`graph':
The graph object to study.
`est':
Pointer to an integer type, the result will be stored here.
`size':
The size of the motif to look for.
`cut_prob':
Vector giving the probabilities to cut a branch of the search tree
and omit counting the motifs in that branch. It contains a
probability for each level. Supply `size' zeros here to count all
the motifs in the sample.
`sample_size':
The number of vertices to use as the sample. This parameter is
only used if the `parsample' argument is a null pointer.
`parsample':
Either pointer to an initialized vector or a null pointer. If a
vector then the vertex ids in the vector are used as a sample. If
a null pointer then the `sample_size' argument is used to create a
sample of vertices drawn with uniform probability.
*Returns:. *
`'
Error code.
*See also:. *
`'
`igraph_motifs_randesu()' (*note igraph_motifs_randesu --- Count
the number of motifs in a graph::), `igraph_motifs_randesu_no()'
(*note igraph_motifs_randesu_no --- Count the total number of
motifs in a graph::).
Time complexity: TODO.
File: igraph_reference_manual.info, Node: igraph_motifs_randesu_callback --- Finds motifs in a graph and calls a function for each of them, Next: igraph_motifs_handler_t --- Callback type for igraph_motifs_randesu_callback, Prev: igraph_motifs_randesu_estimate --- Estimate the total number of motifs in a graph, Up: Graph motifs
17.3.4 igraph_motifs_randesu_callback -- Finds motifs in a graph and calls a function for each of them
------------------------------------------------------------------------------------------------------
int igraph_motifs_randesu_callback(const igraph_t *graph, int size,
const igraph_vector_t *cut_prob, igraph_motifs_handler_t *callback,
void* extra);
Similarly to `igraph_motifs_randesu()' (*note igraph_motifs_randesu
--- Count the number of motifs in a graph::), this function is able to
find the different motifs of size three and four (ie. the number of
different subgraphs with three and four vertices) in the network.
However, instead of counting them, the function will call a callback
function for each motif found to allow further tests or post-processing.
The `cut_prob' argument also allows sampling the motifs, just like
for `igraph_motifs_randesu()' (*note igraph_motifs_randesu --- Count
the number of motifs in a graph::). Set the `cut_prob' argument to a
zero vector for finding all motifs.
*Arguments:. *
`graph':
The graph to find the motifs in.
`size':
The size of the motifs to search for. Only three and four are
implemented currently. The limitation is not in the motif finding
code, but the graph isomorphism code.
`cut_prob':
Vector of probabilities for cutting the search tree at a given
level. The first element is the*