ogdf-python 0.3.3

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

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.

Useful Links

Original repository (GitHub) - Bugtracker and issues (GitHub) - PyPi package (PyPi ogdf-python) - Try it out! (mybinder.org).

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

Quickstart

Click here to start an interactive online Jupyter Notebook with an example OGDF graph where you can try out ogdf-python:

Simply re-run the code cell to see the graph. You can also find further examples next to that Notebook (i.e. via the folder icon on the left). To get a similar Jupyter Notebook with a little more compute power running on your local machine, use the following install command and open the link to localhost/127.0.0.1 that will be printed in your browser:

pip install 'ogdf-python[quickstart]'
jupyter lab

The optional [quickstart] pulls in matplotlib and jupyter lab as well as a ready-to-use binary build of the OGDF via ogdf-wheel. Please note that downloading and installing all dependencies (especially building cppyy) may take a moment. Alternatively, see the instructions below for installing ogdf-python without this if you want to use your own local build of the OGDF.

Usage

ogdf-python works very well with Jupyter:

# %matplotlib widget
# uncomment the above line if you want the interactive display

from ogdf_python import *
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.

Installation without ogdf-wheel

Use pip to install the ogdf-python package locally on your machine. Please note that building cppyy from sources may take a while. Furthermore, you will need a local shared library build (-DBUILD_SHARED_LIBS=ON) of the OGDF. If you didn’t install the 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

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

There seems to be memory leak in the Jupyter Lab server which causes it to use large amounts of memory over time while working with ogdf-python. On Linux, the following command can be used to limit this memory usage:

systemd-run --scope -p MemoryMax=5G --user -- jupyter notebook