How to create a graph?

[szhorvat]

Could you show an example of creating a graph with one of the generators?

There's a difference between how most functions that create graphs vs other data structure (such as vectors) operate. The typical vector operation goes like this: (1) init vector (2) call function that writes data into vector (3) use vector, then destroy it.

With graphs, all graph generators also initialize the graph.

Take for example LibIGraph.ring. For the C function, the first parameter is an uninitialized graph. It will be initialized by igraph_ring() itself. How do you handle this in this package? How do I obtain a "ring graph" (cycle graph) using this constructor?

[Krastanov]

julia> using IGraphs

julia> g = IGraph(); # use the wrapper that internally instantiates a `igraph_t`

julia> LibIGraph.ring(g, 4, false, false, false); # use directly the C function

julia> using Graphs

julia> Graph(IGraph(Graph(g))) == Graph(g) # a quick sanity check that we are not completely borked (by converting between a Graphs.jl and a IGraphs.jl graph)
true

[szhorvat]

Sorry about using issues instead of discussions.

Does g = IGraph(); just create an uninitialized igraph_t then? That would mean that trying to operate on it is likely to cause a segmentation fault.

Is the intention to init and destroy these objects manually? So we also need to do LibIGraph.destroy(g) when we're done working with it?

[Krastanov]

No worries, github discussions were not even enabled when you posted.

g = IGraph() indeed just contains an uninitialized igraph_t in its g.objref field. On garbage collection it does run LibIGraph.destroy(g) so there should be no leaks. But if someone works directly with g before it is initialized with one of the LibIGraph internal functions, it would indeed be useless (but if they use the public API they will get a nice warning about it).

g = IGraph(n::Int) gives me the empty graph of n edges (properly initialized).

There are three ways someone might use g:

1. using the public Graphs.jl interface shared between most graph libraries in julia. E.g. things like Graphs.ne(g::IGraph) which gives me the number of edges (and it is internally implemented as Graphs.ne(g::IGraph) = IGraphs.LibIGraph.ecount(g))
2. using the lowest-level direct C bindings IGraphs.LibIGraph.igraph_ecount(Ref(g.objref))
3. using the non-public low-level wrapper that automatically take care of things like getting references, converting error return values into thrown errors (not fully implemented yet). For each C function LibIGraph.igraph_functionname there is a LibIGraph.functionname which provides that conversion.

Number 1 is the "correct" idiomatic way to use things, but very little will be provided out of the box and neatly wrapped. Basically only what is implemented in https://github.com/JuliaGraphs/IGraphs.jl/blob/master/src/graph_api.jl

Number 2 is kinda silly. If you are going to use the rawest C bindings, you can just as well directly write C-like julia. E.g.

g = LibIGraph.igraph_t() # no wrappers, no automatic garbage collection
LibIGraph.igraph_ring(Ref(g), 5, false, false, false)
c = LibIGraph.igraph_ecount(Ref(g))
LibIGraph.destroy(Ref(g))

Number 3 is what is used in order to implement number 1 and what I imagine most users will rely on until more of the API is neatly wrapped. With your functions.yaml it probably would be straightforward to automate this transition from 3 to 1.

[szhorvat]

Let me put the question like this:

Is it a goal to make the interface "safe", in the sense that it shouldn't be possible to cause a crash (segfault) by misusing it? Or is the plan to keep it very low level, where one must pay attention to the same things as one would when writing C code. Not doing so may result in crashes, memory corruptions, or similar.

igraph's C core is designed to do most error checking, meaning that it should never be possible to trigger a crash from high-level languages. However, there are assumptions about how the interfaces call C functions, which which C functions they call.

Examples:

• Calling igraph_add_edge() with negative vertex IDs will throw a nice friendly error, but won't cause problems. igraph validates the input.
• Calling igraph_add_edge() with an igraph_t that was not initialized will trigger a crash. This is not possible to do from the official interfaces.
• Calling igraph_strvector_get() with an out-of-bounds index will trigger a crash. The index is not validated for performance reasons, and also because this function is not intended to be exposed to high-level interfaces. This is true for basically all functions that manipulate the core data structures, with the exception of igraph_t.

It seems to me that at the moment IGraphs.jl cannot avoid being "unsafe". For example, it cannot tell if an igraph_t * parameter requires an initialized or uninitialized object. This information is not encoded in the C prototypes, so it must either be provided manually or must be taken from the Stimulus interface description (functions.yaml).

[Krastanov]

The functions in the module IGraphs.LibIGraph would not be safe. IGraphs.LibIGraph.igraph_functionname are just the C functions. IGraphs.LibIGraph.functionname are slightly more convenient wrappers around the C functions with slightly automated error handling.

The few function methods defined in the module IGraphs outside of IGraphs.LibIGraph will be safe (checking for initialization, etc). As time passes, more such safe functions probably will be provided.

For the aforementioned safe functions there are various ways in Julia to opt into unsafe behavior for performance reasons. E.g. the @inbounds macro which says to the compiler "you can stop validating indices, I promise all the indices will be correct". Down the line these can be implemented as well, but not particularly a priority right now.