ogdf-python 0.1.2.dev0

Automagic Python Bindings for the Open Graph Drawing Framework written in C++

Original repository (GitHub) - Bugtracker and issues (GitHub) - PyPi package (PyPi ogdf-python) - Documentation (Read The Docs).

Official OGDF website (ogdf.net) - Public OGDF repository (GitHub) - Internal OGDF repository (GitLab) - OGDF Documentation (GitHub / Doxygen) - cppyy Documentation (Read The Docs).

ogdf-python uses the black magic of the awesome cppyy library to automagically generate python bindings for the C++ Open Graph Drawing Framework (OGDF). It is available for Python>=3.6 and is Apache2 licensed. There are no binding definitions files, no stuff that needs extra compiling, it just works™, believe me. Templates, namespaces, cross-language callbacks and inheritance, pythonic iterators and generators, it’s all there. If you want to learn more about the magic behind the curtains, read this article.

Quickstart

First, install the package ogdf-python package. Please note that building cppyy from sources may take a while. If you didn’t install OGDF globally on your system, either set the OGDF_INSTALL_DIR to the prefix you configured in cmake, or set OGDF_BUILD_DIR to the subdirectory of your copy of the OGDF repo where your out-of-source build lives.

$ pip install ogdf-python
$ OGDF_BUILD_DIR=~/ogdf/build-debug python3

Alternatively, ogdf-python works very well with Jupyter:

%env OGDF_BUILD_DIR=~/ogdf/build-debug

from ogdf_python import ogdf, cppinclude
cppinclude("ogdf/basic/graph_generators/randomized.h")
cppinclude("ogdf/layered/SugiyamaLayout.h")

G = ogdf.Graph()
ogdf.setSeed(1)
ogdf.randomPlanarTriconnectedGraph(G, 20, 40)
GA = ogdf.GraphAttributes(G, ogdf.GraphAttributes.all)

for n in G.nodes:
    GA.label[n] = "N%s" % n.index()

SL = ogdf.SugiyamaLayout()
SL.call(GA)
GA

Read the pitfalls section and check out docs/examples/pitfalls.ipynb for the more advanced Sugiyama example from the OGDF docs. There is also a bigger example in docs/examples/ogdf-includes.ipynb. If anything is unclear, check out the python help help(ogdf.Graph) and read the corresponding OGDF documentation.

Pitfalls

See also docs/examples/pitfalls.ipynb for full examples.

OGDF sometimes takes ownership of objects (usually when they are passed as modules), which may conflict with the automatic cppyy garbage collection. Set __python_owns__ = False on those objects to tell cppyy that those objects don’t need to be garbage collected, but will be cleaned up from the C++ side.

SL = ogdf.SugiyamaLayout()
ohl = ogdf.OptimalHierarchyLayout()
ohl.__python_owns__ = False
SL.setLayout(ohl)

When you overwrite a python variable pointing to a C++ object (and it is the only python variable pointing to that object), the C++ object will usually be immediately deleted. This might be a problem if another C++ objects depends on that old object, e.g. a GraphAttributes instance depending on a Graph instance. Now the other C++ object has a pointer to a deleted and now invalid location, which will usually cause issues down the road (e.g. when the dependant object is deleted and wants to deregister from its no longer alive parent). This overwriting might easily happen if you run a Jupyter cell multiple times or some code in a for-loop. Please ensure that you always overwrite or delete dependent C++ variables in the reverse order of their initialization.

for i in range(5):
    # clean-up all variables
    CGA = CG = G = None # note that order is different from C++, CGA will be deleted first, G last
    # now we can re-use them
    G = ogdf.Graph()
    CG = ogdf.ClusterGraph(G)
    CGA = ogdf.ClusterGraphAttributes(CG, ogdf.ClusterGraphAttributes.all)

    # alternatively manually clean up in the right order
    del CGA
    del CG
    del G