simpgraph: Minimal Python Module for Unordered Graphs
================================================================
Introduction
============
``simpgraph`` is a simple and minimal Python module for unordered graphs.
An *unordered graph*, simply called a *graph*, is a pair of a set of elements, called *vertices*,
and a set of (unordered) vertex pairs, called *edges*.
In this module, a graph is assumed to have no *loop*, an edge whose vertices
are identical with each other, and all edges have no direction.
Installation
============
.. code:: shell-session
$ pip install simpgraph
Usage
=====
Let us import ``simpgraph`` module, create an empty graph,
and add edges (and vertices if necessary).
.. code:: python
from simpgraph import SimpGraph
# empty graph
g = SimpGraph()
# 1
# |
# 4---3
g.add_edge(4,1)
g.add_edge(4,3)
assert set(g.all_vertices()) == {1,3,4}
assert g.num_vertices() == 3
assert g.max_vertex() == 4 # not always equal to the number of vertices
assert set(g.adj_vertices(1)) == {4}
assert set(g.adj_vertices(3)) == {4}
assert set(g.adj_vertices(4)) == {1,3}
assert g.num_edges() == 2
g.add_edge(1,4) # the edge between 1 and 4 already added and nothing done
assert g.num_edges() == 2
As above, ``add_edge(u,v)`` adds, to the edge set,
the edge between vertices ``u,v`` given in its arguments in an arbitrary order.
New vertices, if included in the added edge, are also added to the vertex set.
If the edge is present in the edge set, the method does nothing.
.. code:: python
#
# 1 2
# |
# 4---3
g.add_vertex(2)
assert set(g.all_vertices()) == {1,2,3,4}
assert set(g.all_edges()) == {(1,4),(3,4)}
assert set(g.adj_vertices(2)) == set() # isolated vertex
assert g.num_vertices() == 4
g.add_vertex(1) # vertex 1 already present and nothing done
assert g.num_vertices() == 4
Similary, ``add_vertex(u)`` adds vertex ``u`` to the vertex set.
If it is present in the vertex set, nothing is done.
.. code:: python
# before after
# 1 2 1 2
# | => |
# 4---3 4
g.discard_vertex(3)
assert set(g.all_vertices()) == {1,2,4}
assert set(g.all_edges()) == {(1,4)}
assert g.num_vertices() == 3
g.discard_vertex(3) # vertex 3 already discarded and nothing done
assert g.num_vertices() == 3
As above, ``discard_vertex(u)`` discards not only vertex ``u``
but also all edges incident to ``u``.
If the vertex is not present in the graph, nothing is done
and no exception raises
.. code:: python
# before after
# 1 2 1 2
# | =>
# 4 4
g.discard_edge(1,4)
assert set(g.all_vertices()) == {1,2,4}
assert set(g.all_edges()) == set()
assert g.num_edges() == 0
g.discard_edge(1,4)
assert g.num_edges() == 0
Similary, ``discard_edge(u,v)`` discards the edge between ``u`` and ``v``
If the edge is not present in the graph, nothing is done and no exception
raises.
.. code:: python
# before after
# 1 2
# =>
# 4
g.clear()
assert g.num_vertices() == 0
assert g.num_edges() == 0
``clear()`` clears all variables of graph ``g`` and makes it an empty graph.
.. code:: python
# 1 2:B
# |A |
# 4 3:C
g.add_edge(2,3)
g.add_edge(1,4, label="A")
g.add_vertex(2, label="B")
g.add_vertex(3, label="C")
assert g.vertex_label(1) is None
assert g.vertex_label(2) == "B"
assert g.vertex_label(3) == "C"
assert g.vertex_label(4) is None
assert g.edge_label(2,3) is None
assert g.edge_label(1,4) == "A"
# before after
# 1 2:B 1 2:B
# |A | => |A |D
# 4 3:C 4 3:C
g.add_edge(2,3, label="D") # label updated
Optional labels can be assigned to vertices and edges,
and the graph can be rendered as follows.
.. code:: python
g.render(filename="sample", format="png")
As a result, ``sample.png`` will be generated.
The arguments of ``render()`` are the same as those of ``render()`` of
Graphviz.
See `User Guide of Graphviz
<https://graphviz.readthedocs.io/en/stable/manual.html>`__ .
.. code:: python
# 1 2:B
# |A |D
# 4 3:C
g.add_edge(1,2, label="D")
with open("sample.col", "w") as f:
f.write(f"p {g.max_vertex()} {g.num_edges()}\n")
for u in g.all_vertices():
f.write(f"n {u}\n")
for u,v in g.all_edges():
f.write(f"e {u} {v}\n")
f.seek(0)
gg = SimpGraph.read(filename="sample.col", format="DIMACS")
assert(g == gg) # the vertex set and the edge set are determined to be equal.
# However, no label is preserved in the constructed graph.
# 1 2
# | |
# 4 3
assert gg.vertex_label(2) is None
assert gg.vertex_label(3) is None
assert gg.edge_label(1,4) is None
assert gg.edge_label(2,3) is None
As above, a graph can be wrote to an external file in DIMACS graph format,
but vertex labels and edge labels are not recorded.
Class method ``SimpGraph.read()`` reads such a file and construct a graph,
and the resulted graph ``g`` is equal to the original graph ``g``
in that they have the same vertex set and the same edge set.
(Note: the vertex labels and the edge labels are not considered).
Bugs/Requests/Discussions
=========================
Please report bugs and requests from `GitHub Issues
<https://github.com/toda-lab/simpgraph/issues>`__ , and
ask questions from `GitHub Discussions <https://github.com/toda-lab/simpgraph/discussions>`__ .
License
=======
Please see `LICENSE <https://github.com/toda-lab/simpgraph/blob/main/LICENSE>`__ .
Raw data
{
"_id": null,
"home_page": "https://github.com/toda-lab/simpgraph",
"name": "simpgraph",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "mathematics, graph",
"author": "Takahisa Toda",
"author_email": "toda@disc.lab.uec.ac.jp",
"download_url": "https://files.pythonhosted.org/packages/0c/f0/ecf7be20e5e5cebda4981f30a706697ade243bc3353491793a178b77a80c/simpgraph-1.0.0.tar.gz",
"platform": null,
"description": "simpgraph: Minimal Python Module for Unordered Graphs\n================================================================\n\nIntroduction\n============\n``simpgraph`` is a simple and minimal Python module for unordered graphs.\nAn *unordered graph*, simply called a *graph*, is a pair of a set of elements, called *vertices*, \nand a set of (unordered) vertex pairs, called *edges*.\nIn this module, a graph is assumed to have no *loop*, an edge whose vertices\nare identical with each other, and all edges have no direction.\n\nInstallation\n============\n\n.. code:: shell-session\n\n $ pip install simpgraph\n\nUsage\n=====\n\nLet us import ``simpgraph`` module, create an empty graph, \nand add edges (and vertices if necessary).\n\n.. code:: python\n\n from simpgraph import SimpGraph\n\n # empty graph\n g = SimpGraph()\n\n # 1\n # | \n # 4---3\n g.add_edge(4,1)\n g.add_edge(4,3)\n\n assert set(g.all_vertices()) == {1,3,4}\n assert g.num_vertices() == 3\n assert g.max_vertex() == 4 # not always equal to the number of vertices\n\n assert set(g.adj_vertices(1)) == {4}\n assert set(g.adj_vertices(3)) == {4}\n assert set(g.adj_vertices(4)) == {1,3}\n\n assert g.num_edges() == 2\n g.add_edge(1,4) # the edge between 1 and 4 already added and nothing done\n assert g.num_edges() == 2\n\nAs above, ``add_edge(u,v)`` adds, to the edge set, \nthe edge between vertices ``u,v`` given in its arguments in an arbitrary order.\nNew vertices, if included in the added edge, are also added to the vertex set.\nIf the edge is present in the edge set, the method does nothing.\n\n.. code:: python\n\n #\n # 1 2\n # | \n # 4---3\n g.add_vertex(2)\n\n assert set(g.all_vertices()) == {1,2,3,4}\n assert set(g.all_edges()) == {(1,4),(3,4)}\n\n assert set(g.adj_vertices(2)) == set() # isolated vertex\n\n assert g.num_vertices() == 4\n g.add_vertex(1) # vertex 1 already present and nothing done\n assert g.num_vertices() == 4\n\nSimilary, ``add_vertex(u)`` adds vertex ``u`` to the vertex set.\nIf it is present in the vertex set, nothing is done.\n\n.. code:: python\n\n # before after \n # 1 2 1 2\n # | => |\n # 4---3 4 \n g.discard_vertex(3)\n \n assert set(g.all_vertices()) == {1,2,4}\n assert set(g.all_edges()) == {(1,4)}\n\n assert g.num_vertices() == 3\n g.discard_vertex(3) # vertex 3 already discarded and nothing done\n assert g.num_vertices() == 3\n\nAs above, ``discard_vertex(u)`` discards not only vertex ``u`` \nbut also all edges incident to ``u``.\nIf the vertex is not present in the graph, nothing is done \nand no exception raises\n\n.. code:: python\n\n # before after \n # 1 2 1 2\n # | => \n # 4 4 \n g.discard_edge(1,4)\n\n assert set(g.all_vertices()) == {1,2,4}\n assert set(g.all_edges()) == set()\n\n assert g.num_edges() == 0\n g.discard_edge(1,4)\n assert g.num_edges() == 0\n\nSimilary, ``discard_edge(u,v)`` discards the edge between ``u`` and ``v``\nIf the edge is not present in the graph, nothing is done and no exception\nraises.\n\n.. code:: python\n\n # before after \n # 1 2 \n # => \n # 4 \n g.clear()\n\n assert g.num_vertices() == 0\n assert g.num_edges() == 0\n\n``clear()`` clears all variables of graph ``g`` and makes it an empty graph.\n\n.. code:: python\n\n # 1 2:B\n # |A |\n # 4 3:C\n g.add_edge(2,3)\n g.add_edge(1,4, label=\"A\")\n g.add_vertex(2, label=\"B\")\n g.add_vertex(3, label=\"C\")\n\n assert g.vertex_label(1) is None\n assert g.vertex_label(2) == \"B\"\n assert g.vertex_label(3) == \"C\"\n assert g.vertex_label(4) is None\n\n assert g.edge_label(2,3) is None\n assert g.edge_label(1,4) == \"A\"\n\n # before after\n # 1 2:B 1 2:B\n # |A | => |A |D\n # 4 3:C 4 3:C\n g.add_edge(2,3, label=\"D\") # label updated\n\nOptional labels can be assigned to vertices and edges,\nand the graph can be rendered as follows.\n\n.. code:: python\n\n g.render(filename=\"sample\", format=\"png\")\n\nAs a result, ``sample.png`` will be generated.\nThe arguments of ``render()`` are the same as those of ``render()`` of\nGraphviz.\nSee `User Guide of Graphviz\n<https://graphviz.readthedocs.io/en/stable/manual.html>`__ .\n\n.. code:: python\n\n # 1 2:B\n # |A |D\n # 4 3:C\n g.add_edge(1,2, label=\"D\")\n with open(\"sample.col\", \"w\") as f:\n f.write(f\"p {g.max_vertex()} {g.num_edges()}\\n\")\n for u in g.all_vertices():\n f.write(f\"n {u}\\n\")\n for u,v in g.all_edges():\n f.write(f\"e {u} {v}\\n\")\n f.seek(0)\n\n gg = SimpGraph.read(filename=\"sample.col\", format=\"DIMACS\")\n\n assert(g == gg) # the vertex set and the edge set are determined to be equal.\n\n # However, no label is preserved in the constructed graph.\n # 1 2\n # | |\n # 4 3\n assert gg.vertex_label(2) is None\n assert gg.vertex_label(3) is None\n assert gg.edge_label(1,4) is None\n assert gg.edge_label(2,3) is None\n\nAs above, a graph can be wrote to an external file in DIMACS graph format,\nbut vertex labels and edge labels are not recorded.\nClass method ``SimpGraph.read()`` reads such a file and construct a graph,\nand the resulted graph ``g`` is equal to the original graph ``g``\nin that they have the same vertex set and the same edge set.\n(Note: the vertex labels and the edge labels are not considered).\n\nBugs/Requests/Discussions\n=========================\n\nPlease report bugs and requests from `GitHub Issues\n<https://github.com/toda-lab/simpgraph/issues>`__ , and \nask questions from `GitHub Discussions <https://github.com/toda-lab/simpgraph/discussions>`__ .\n\nLicense\n=======\n\nPlease see `LICENSE <https://github.com/toda-lab/simpgraph/blob/main/LICENSE>`__ .\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple and minimal Python module for unordered graphs",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/toda-lab/simpgraph",
"Repository": "https://github.com/toda-lab/simpgraph"
},
"split_keywords": [
"mathematics",
" graph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "582e75e94d3047a503aff2debd942f612027523033241451ef1cfa8785f4305d",
"md5": "0832f311b61c1eccb98a8648714c6ed0",
"sha256": "15ce625e35d91b5b7ed69b317e5574701a0b3eecf5efaf19d5d0f9ffd77563cf"
},
"downloads": -1,
"filename": "simpgraph-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0832f311b61c1eccb98a8648714c6ed0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 6705,
"upload_time": "2024-09-05T14:23:37",
"upload_time_iso_8601": "2024-09-05T14:23:37.298473Z",
"url": "https://files.pythonhosted.org/packages/58/2e/75e94d3047a503aff2debd942f612027523033241451ef1cfa8785f4305d/simpgraph-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0cf0ecf7be20e5e5cebda4981f30a706697ade243bc3353491793a178b77a80c",
"md5": "41a00a4cbd0b0e29c46b66df0103589e",
"sha256": "2e355d9d22f6604b7e3ec8addc44434e2834cb1139dad91798e930170d8ba691"
},
"downloads": -1,
"filename": "simpgraph-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "41a00a4cbd0b0e29c46b66df0103589e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 6042,
"upload_time": "2024-09-05T14:23:40",
"upload_time_iso_8601": "2024-09-05T14:23:40.081297Z",
"url": "https://files.pythonhosted.org/packages/0c/f0/ecf7be20e5e5cebda4981f30a706697ade243bc3353491793a178b77a80c/simpgraph-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 14:23:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "toda-lab",
"github_project": "simpgraph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "simpgraph"
}
JSON
