| Name | ogdf-python JSON |
| Version |
0.3.3
JSON |
| download |
| home_page | None |
| Summary | Automagic Python Bindings for the Open Graph Drawing Framework written in C++ |
| upload_time | 2024-08-16 17:12:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
algorithm
drawing
graph
network
ogdf
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. |binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/N-Coder/ogdf-python/HEAD?labpath=docs%2Fexamples%2Fsugiyama-simple.ipynb
.. |(TM)| unicode:: U+2122
ogdf-python 0.3.3: Automagic Python Bindings for the Open Graph Drawing Framework |binder|
==============================================================================================
``ogdf-python`` uses the `black magic <http://www.camillescott.org/2019/04/11/cmake-cppyy/>`_
of the awesome `cppyy <https://bitbucket.org/wlav/cppyy/src/master/>`_ library to automagically generate python bindings
for the C++ `Open Graph Drawing Framework (OGDF) <https://ogdf.uos.de/>`_.
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\ |(TM)|, 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 <http://www.camillescott.org/2019/04/11/cmake-cppyy/>`_.
Useful Links
------------
`Original repository <https://github.com/N-Coder/ogdf-python>`_ (GitHub) -
`Bugtracker and issues <https://github.com/N-Coder/ogdf-python>`_ (GitHub) -
`PyPi package <https://pypi.python.org/pypi/ogdf-python>`_ (PyPi ``ogdf-python``) -
`Try it out! <https://mybinder.org/v2/gh/N-Coder/ogdf-python/HEAD?labpath=docs%2Fexamples%2Fsugiyama-simple.ipynb>`_ (mybinder.org).
`Official OGDF website <https://ogdf.uos.de/>`_ (ogdf.net) -
`Public OGDF repository <https://github.com/ogdf/ogdf>`_ (GitHub) -
`OGDF Documentation <https://ogdf.github.io/docs/ogdf/>`_ (GitHub / Doxygen) -
`cppyy Documentation <https://cppyy.readthedocs.io>`_ (Read The Docs).
..
`Documentation <https://ogdf-python.readthedocs.io>`_ (Read The Docs)
`Internal OGDF repository <https://git.tcs.uos.de/ogdf-devs/OGDF>`_ (GitLab)
Quickstart
----------
Click here to start an interactive online Jupyter Notebook with an example OGDF graph where you can try out ``ogdf-python``: |binder|
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:
.. code-block:: bash
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 <https://github.com/ogdf/ogdf-wheel>`_.
Please note that downloading and installing all dependencies (especially building ``cppyy``) may take a moment.
Alternatively, see the instructions `below <#manual-installation>`_ 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:
.. code-block:: python
# %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
.. image:: docs/examples/sugiyama-simple.svg
:target: docs/examples/sugiyama-simple.ipynb
:alt: SugiyamaLayouted Graph
:height: 300 px
Read the `pitfalls section <#pitfalls>`_ and check out `docs/examples/pitfalls.ipynb <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 <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 <https://ogdf.github.io/doc/ogdf/md_doc_build.html>`_.
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 <https://ogdf.github.io/doc/ogdf/md_doc_build.html#autotoc_md4>`_ lives.
.. code-block:: bash
$ pip install ogdf-python
$ OGDF_BUILD_DIR=~/ogdf/build-debug python3
Pitfalls
--------
See also `docs/examples/pitfalls.ipynb <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.
.. code-block:: python
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.
.. code-block:: python
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:
.. code-block:: bash
systemd-run --scope -p MemoryMax=5G --user -- jupyter notebook
Raw data
{
"_id": null,
"home_page": null,
"name": "ogdf-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "algorithm, drawing, graph, network, ogdf",
"author": null,
"author_email": "\"Simon D. Fink\" <finksim@fim.uni-passau.de>",
"download_url": "https://files.pythonhosted.org/packages/94/09/03252de67e123d9d620342dec15d9f1cfaf86b00a1f1665e3223688c0166/ogdf_python-0.3.3.tar.gz",
"platform": null,
"description": ".. |binder| image:: https://mybinder.org/badge_logo.svg\n :target: https://mybinder.org/v2/gh/N-Coder/ogdf-python/HEAD?labpath=docs%2Fexamples%2Fsugiyama-simple.ipynb\n.. |(TM)| unicode:: U+2122\n\nogdf-python 0.3.3: Automagic Python Bindings for the Open Graph Drawing Framework |binder|\n==============================================================================================\n\n``ogdf-python`` uses the `black magic <http://www.camillescott.org/2019/04/11/cmake-cppyy/>`_\nof the awesome `cppyy <https://bitbucket.org/wlav/cppyy/src/master/>`_ library to automagically generate python bindings\nfor the C++ `Open Graph Drawing Framework (OGDF) <https://ogdf.uos.de/>`_.\nIt is available for Python>=3.6 and is Apache2 licensed.\nThere are no binding definitions files, no stuff that needs extra compiling, it just works\\ |(TM)|, believe me.\nTemplates, namespaces, cross-language callbacks and inheritance, pythonic iterators and generators, it's all there.\nIf you want to learn more about the magic behind the curtains, read `this article <http://www.camillescott.org/2019/04/11/cmake-cppyy/>`_.\n\nUseful Links\n------------\n`Original repository <https://github.com/N-Coder/ogdf-python>`_ (GitHub) -\n`Bugtracker and issues <https://github.com/N-Coder/ogdf-python>`_ (GitHub) -\n`PyPi package <https://pypi.python.org/pypi/ogdf-python>`_ (PyPi ``ogdf-python``) -\n`Try it out! <https://mybinder.org/v2/gh/N-Coder/ogdf-python/HEAD?labpath=docs%2Fexamples%2Fsugiyama-simple.ipynb>`_ (mybinder.org).\n\n`Official OGDF website <https://ogdf.uos.de/>`_ (ogdf.net) -\n`Public OGDF repository <https://github.com/ogdf/ogdf>`_ (GitHub) -\n`OGDF Documentation <https://ogdf.github.io/docs/ogdf/>`_ (GitHub / Doxygen) -\n`cppyy Documentation <https://cppyy.readthedocs.io>`_ (Read The Docs).\n\n..\n `Documentation <https://ogdf-python.readthedocs.io>`_ (Read The Docs)\n `Internal OGDF repository <https://git.tcs.uos.de/ogdf-devs/OGDF>`_ (GitLab)\n\n\nQuickstart\n----------\n\nClick here to start an interactive online Jupyter Notebook with an example OGDF graph where you can try out ``ogdf-python``: |binder|\n\nSimply 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).\nTo 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:\n\n.. code-block:: bash\n\n pip install 'ogdf-python[quickstart]'\n jupyter lab\n\nThe optional ``[quickstart]`` pulls in matplotlib and jupyter lab as well as a ready-to-use binary build of the OGDF via `ogdf-wheel <https://github.com/ogdf/ogdf-wheel>`_.\nPlease note that downloading and installing all dependencies (especially building ``cppyy``) may take a moment.\nAlternatively, see the instructions `below <#manual-installation>`_ for installing ``ogdf-python`` without this if you want to use your own local build of the OGDF.\n\nUsage\n-----\n``ogdf-python`` works very well with Jupyter:\n\n.. code-block:: python\n\n # %matplotlib widget\n # uncomment the above line if you want the interactive display\n\n from ogdf_python import *\n cppinclude(\"ogdf/basic/graph_generators/randomized.h\")\n cppinclude(\"ogdf/layered/SugiyamaLayout.h\")\n\n G = ogdf.Graph()\n ogdf.setSeed(1)\n ogdf.randomPlanarTriconnectedGraph(G, 20, 40)\n GA = ogdf.GraphAttributes(G, ogdf.GraphAttributes.all)\n\n for n in G.nodes:\n GA.label[n] = \"N%s\" % n.index()\n\n SL = ogdf.SugiyamaLayout()\n SL.call(GA)\n GA\n\n.. image:: docs/examples/sugiyama-simple.svg\n :target: docs/examples/sugiyama-simple.ipynb\n :alt: SugiyamaLayouted Graph\n :height: 300 px\n\nRead the `pitfalls section <#pitfalls>`_ and check out `docs/examples/pitfalls.ipynb <docs/examples/pitfalls.ipynb>`_\nfor the more advanced Sugiyama example from the OGDF docs.\nThere is also a bigger example in `docs/examples/ogdf-includes.ipynb <docs/examples/ogdf-includes.ipynb>`_.\nIf anything is unclear, check out the python help ``help(ogdf.Graph)`` and read the corresponding OGDF documentation.\n\nInstallation without ogdf-wheel\n-------------------------------\n\nUse pip to install the ``ogdf-python`` package locally on your machine.\nPlease note that building ``cppyy`` from sources may take a while.\nFurthermore, you will need a local shared library build (``-DBUILD_SHARED_LIBS=ON``) of the `OGDF <https://ogdf.github.io/doc/ogdf/md_doc_build.html>`_.\nIf you didn't install the OGDF globally on your system,\neither set the ``OGDF_INSTALL_DIR`` to the prefix you configured in ``cmake``,\nor set ``OGDF_BUILD_DIR`` to the subdirectory of your copy of the OGDF repo where your\n`out-of-source build <https://ogdf.github.io/doc/ogdf/md_doc_build.html#autotoc_md4>`_ lives.\n\n.. code-block:: bash\n\n $ pip install ogdf-python\n $ OGDF_BUILD_DIR=~/ogdf/build-debug python3\n\nPitfalls\n--------\n\nSee also `docs/examples/pitfalls.ipynb <docs/examples/pitfalls.ipynb>`_ for full examples.\n\nOGDF sometimes takes ownership of objects (usually when they are passed as modules),\nwhich may conflict with the automatic cppyy garbage collection.\nSet ``__python_owns__ = False`` on those objects to tell cppyy that those objects\ndon't need to be garbage collected, but will be cleaned up from the C++ side.\n\n.. code-block:: python\n\n SL = ogdf.SugiyamaLayout()\n ohl = ogdf.OptimalHierarchyLayout()\n ohl.__python_owns__ = False\n SL.setLayout(ohl)\n\nWhen you overwrite a python variable pointing to a C++ object (and it is the only\npython variable pointing to that object), the C++ object will usually be immediately deleted.\nThis might be a problem if another C++ objects depends on that old object, e.g.\na ``GraphAttributes`` instance depending on a ``Graph`` instance.\nNow the other C++ object has a pointer to a deleted and now invalid location,\nwhich will usually cause issues down the road (e.g. when the dependant object is\ndeleted and wants to deregister from its no longer alive parent).\nThis overwriting might easily happen if you run a Jupyter cell multiple times or some code in a ``for``-loop.\nPlease ensure that you always overwrite or delete dependent C++ variables in\nthe reverse order of their initialization.\n\n.. code-block:: python\n\n for i in range(5):\n # clean-up all variables\n CGA = CG = G = None # note that order is different from C++, CGA will be deleted first, G last\n # now we can re-use them\n G = ogdf.Graph()\n CG = ogdf.ClusterGraph(G)\n CGA = ogdf.ClusterGraphAttributes(CG, ogdf.ClusterGraphAttributes.all)\n\n # alternatively manually clean up in the right order\n del CGA\n del CG\n del G\n\nThere seems to be memory leak in the Jupyter Lab server which causes it to use large amounts of memory\nover time while working with ogdf-python. On Linux, the following command can be used to limit this memory usage:\n\n.. code-block:: bash\n\n systemd-run --scope -p MemoryMax=5G --user -- jupyter notebook\n",
"bugtrack_url": null,
"license": null,
"summary": "Automagic Python Bindings for the Open Graph Drawing Framework written in C++",
"version": "0.3.3",
"project_urls": null,
"split_keywords": [
"algorithm",
" drawing",
" graph",
" network",
" ogdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31fd5d90155bd9c16a1cda085684872e2ffe6919807c7dbea48d414c76c19be1",
"md5": "226df1abb90ec8b5ea23b2a0b76b58c8",
"sha256": "098aaf723a1b31da245581fd9fc42235f3a39f119634a5a35b8dffe6a8ac386e"
},
"downloads": -1,
"filename": "ogdf_python-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "226df1abb90ec8b5ea23b2a0b76b58c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 792340,
"upload_time": "2024-08-16T17:11:58",
"upload_time_iso_8601": "2024-08-16T17:11:58.348929Z",
"url": "https://files.pythonhosted.org/packages/31/fd/5d90155bd9c16a1cda085684872e2ffe6919807c7dbea48d414c76c19be1/ogdf_python-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "940903252de67e123d9d620342dec15d9f1cfaf86b00a1f1665e3223688c0166",
"md5": "eb605ee5ce0022e90436a3f26d0ed206",
"sha256": "26b88dd4edd9259f17bb820ed631e740235e50077b4a8d3a526466f3ba25b79d"
},
"downloads": -1,
"filename": "ogdf_python-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "eb605ee5ce0022e90436a3f26d0ed206",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 1538658,
"upload_time": "2024-08-16T17:12:03",
"upload_time_iso_8601": "2024-08-16T17:12:03.524867Z",
"url": "https://files.pythonhosted.org/packages/94/09/03252de67e123d9d620342dec15d9f1cfaf86b00a1f1665e3223688c0166/ogdf_python-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 17:12:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ogdf-python"
}
