diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 478eac67d175f4a3242fe5e601992b3df8e564fd..9c5f5fb8681415de86b9cd9ab05b16a56dbe5422 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,12 +35,12 @@ jobs: - name: "Main Script" run: | EXTRA_INSTALL="numpy pybind11" - + # https://numpy.org/doc/stable/user/building.html#accelerated-blas-lapack-libraries # e.g. https://github.com/inducer/pymetis/runs/1303882565?check_suite_focus=true export NPY_BLAS_ORDER="" export NPY_LAPACK_ORDER="" - + curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/main/build-and-test-py-project.sh . ./build-and-test-py-project.sh @@ -62,4 +62,22 @@ jobs: curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/main/build-and-test-py-project.sh . ./build-and-test-py-project.sh + + docs: + name: Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - + uses: actions/setup-python@v1 + with: + python-version: '3.x' + - name: "Main Script" + run: | + EXTRA_INSTALL="numpy pybind11" + curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/main/ci-support.sh + . ci-support.sh + build_py_project_in_venv + build_docs + # vim: sw=4 diff --git a/.gitignore b/.gitignore index 0b4f72a22b864b61796a40f5d7dd8c9d3a571db4..a5272fcc9ffc3d6a2e656f00edcd50259ebd4196 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ .*.swo build siteconf.py -Makefile +/Makefile tags *.vtk *.png diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 53699a43ea72a4b52769a29c87ab27b4c7375987..2244bb53b3806b1510f1ee3c0b0b1eac54691a16 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -22,3 +22,10 @@ Python 3: reports: junit: test/pytest.xml +Documentation: + script: + - EXTRA_INSTALL="numpy pybind11" + - curl -L -O -k https://gitlab.tiker.net/inducer/ci-support/raw/main/build-docs.sh + - ". ./build-docs.sh" + tags: + - python3 diff --git a/README.rst b/README.rst index 40d8f640d5f78fce87b36c831b270d1e34d54e90..a3dd8e741943e28dc392b6b2914c92f360dd0379 100644 --- a/README.rst +++ b/README.rst @@ -36,7 +36,7 @@ This graph, adapted from Figure 2 of the Metis `manual `_ to use zero-based indexing, -.. image:: images/tiny_01.png +.. image:: doc/_static/tiny_01.png can be defined and partitioned into two graphs with @@ -58,5 +58,5 @@ can be defined and partitioned into two graphs with nodes_part_0 = np.argwhere(np.array(membership) == 0).ravel() # [3, 5, 6] nodes_part_1 = np.argwhere(np.array(membership) == 1).ravel() # [0, 1, 2, 4] -.. image:: images/tiny_01_partitioned.png +.. image:: doc/_static/tiny_01_partitioned.png diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..e35d8850c9688b1ce82711694692cc574a799396 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..d4bb2cbb9eddb1bb1b4f366623044af8e4830919 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/images/README b/doc/_static/README similarity index 100% rename from images/README rename to doc/_static/README diff --git a/images/tiny_01.drawio b/doc/_static/tiny_01.drawio similarity index 100% rename from images/tiny_01.drawio rename to doc/_static/tiny_01.drawio diff --git a/images/tiny_01.png b/doc/_static/tiny_01.png similarity index 100% rename from images/tiny_01.png rename to doc/_static/tiny_01.png diff --git a/images/tiny_01_partitioned.drawio b/doc/_static/tiny_01_partitioned.drawio similarity index 100% rename from images/tiny_01_partitioned.drawio rename to doc/_static/tiny_01_partitioned.drawio diff --git a/images/tiny_01_partitioned.png b/doc/_static/tiny_01_partitioned.png similarity index 100% rename from images/tiny_01_partitioned.png rename to doc/_static/tiny_01_partitioned.png diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..209b768973030c0ecced5d6d61da956eb76368c9 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,61 @@ +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "pymetis" +copyright = "2013-2021, Andreas Kloeckner" +author = "Andreas Kloeckner" + + +def get_version(): + conf = {} + exec( + compile( + open("../pymetis/__init__.py").read(), "../pymetis/__init__.py", "exec" + ), + conf, + ) + return conf["version"] + + +version = get_version() + +# -- General configuration --------------------------------------------------- + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx_copybutton", +] + + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/doc/functionality.rst b/doc/functionality.rst new file mode 100644 index 0000000000000000000000000000000000000000..362455b3fe7c32527cd6b74c83cff876201289ae --- /dev/null +++ b/doc/functionality.rst @@ -0,0 +1,4 @@ +Functionality +============= + +.. automodule:: pymetis diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..5a29d60b34202fcba0ac6d9a628c751ca49938f0 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,51 @@ +Welcome to pymetis's documentation! +=================================== + +Quick Start +----------- + +This graph, adapted from Figure 2 of the Metis +`manual `_ to +use zero-based indexing, + +.. image:: _static/tiny_01.png + +can be defined and partitioned into two graphs with + +.. code:: python + + import numpy as np + import pymetis + adjacency_list = [np.array([4, 2, 1]), + np.array([0, 2, 3]), + np.array([4, 3, 1, 0]), + np.array([1, 2, 5, 6]), + np.array([0, 2, 5]), + np.array([4, 3, 6]), + np.array([5, 3])] + n_cuts, membership = pymetis.part_graph(2, adjacency=adjacency_list) + # n_cuts = 3 + # membership = [1, 1, 1, 0, 1, 0, 0] + + nodes_part_0 = np.argwhere(np.array(membership) == 0).ravel() # [3, 5, 6] + nodes_part_1 = np.argwhere(np.array(membership) == 1).ravel() # [0, 1, 2, 4] + +.. image:: _static/tiny_01_partitioned.png + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + functionality + misc + 🚀 Github + 💾 Download Releases + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..2119f51099bf37e4fdb6071dce9f451ea44c62dd --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/misc.rst b/doc/misc.rst new file mode 100644 index 0000000000000000000000000000000000000000..595eca73019535521a6008217f74237ff0f8d1a7 --- /dev/null +++ b/doc/misc.rst @@ -0,0 +1,18 @@ +Installation +============ + +This tutorial will walk you through the process of building pymetis. To follow, +you really only need three basic things: + +* A UNIX-like machine with web access. +* A C++ compiler, preferably a Version 4.x gcc. +* A working `Python `_ installation, Version 3.6 or newer. + +With those prerequisites, the following command should suffice:: + + pip install pymetis + +License +======= + +.. include:: ../LICENSE diff --git a/doc/upload-docs.sh b/doc/upload-docs.sh new file mode 100755 index 0000000000000000000000000000000000000000..c8c6712a55c14d3b18ba4708d7373ebdf4ae5cad --- /dev/null +++ b/doc/upload-docs.sh @@ -0,0 +1,3 @@ +#! /bin/sh + +rsync --verbose --archive --delete _build/html/* doc-upload:doc/pymetis diff --git a/pymetis/__init__.py b/pymetis/__init__.py index cb01aec69e01305f52aec7ce5d26daaa7d58bccc..f46572ad0f537f8ca46b8d27604c5bdb9f9e822f 100644 --- a/pymetis/__init__.py +++ b/pymetis/__init__.py @@ -1,4 +1,8 @@ -from __future__ import division, absolute_import +""" +.. autofunction:: nested_dissection +.. autofunction:: part_graph +.. autofunction:: verify_nd +""" __copyright__ = "Copyright (C) 2009-2013 Andreas Kloeckner" @@ -57,8 +61,8 @@ def nested_dissection(adjacency=None, xadj=None, adjncy=None): """This function computes fill reducing orderings of sparse matrices using the multilevel nested dissection algorithm. - The input graph is given as either a Pythonic way as the `adjacency' parameter - or in the direct C-like way that Metis likes as `xadj' and `adjncy'. It + The input graph is given as either a Pythonic way as the *adjacency* parameter + or in the direct C-like way that Metis likes as *xadj* and *adjncy*. It is an error to specify both graph inputs. """ xadj, adjncy = _prepare_graph(adjacency, xadj, adjncy) @@ -71,15 +75,15 @@ def part_graph(nparts, adjacency=None, xadj=None, adjncy=None, vweights=None, eweights=None, recursive=None, contiguous=None): """Return a partition (cutcount, part_vert) into nparts for an input graph. - The input graph is given in either a Pythonic way as the `adjacency' parameter - or in the direct C-like way that Metis likes as `xadj' and `adjncy'. It + The input graph is given in either a Pythonic way as the *adjacency* parameter + or in the direct C-like way that Metis likes as *xadj* and *adjncy*. It is an error to specify both graph inputs. - The Pythonic graph specifier `adjacency' is required to have the following + The Pythonic graph specifier *adjacency* is required to have the following properties: - len(adjacency) needs to return the number of vertices - - adjacency[i] needs to be an iterable of vertices adjacent to vertex i. + - ``adjacency[i]`` needs to be an iterable of vertices adjacent to vertex i. Both directions of an undirected graph edge are required to be stored. If you would like to use *eweights* (edge weights), you need to use the diff --git a/setup.cfg b/setup.cfg index 23449642ab121444a42c928a362d85d416596a9a..28eb9c6156a5362396333de11682944d5dfa6cb0 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,3 +1,7 @@ [flake8] ignore = E126,E127,E128,E123,E226,E241,E242,W503,E402 max-line-length=85 + +inline-quotes = " +docstring-quotes = """ +multiline-quotes = """ diff --git a/src/.gitignore b/src/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..f3c7a7c5da68804a1bdf391127ba34aed33c3cca --- /dev/null +++ b/src/.gitignore @@ -0,0 +1 @@ +Makefile diff --git a/test/test_metis.py b/test/test_metis.py index 4c100263dafc504a026bbf5f1c9ef45f4376b2e1..e0d41c76d556bf2d58f322520b3015b2398cc0e7 100644 --- a/test/test_metis.py +++ b/test/test_metis.py @@ -86,7 +86,7 @@ def test_tet_mesh(visualize=False): pyvtk.UnstructuredGrid(mesh.points, tetra=mesh.elements), "Mesh", pyvtk.CellData(pyvtk.Scalars(part_vert, name="partition"))) - vtkelements.tofile('split.vtk') + vtkelements.tofile("split.vtk") def test_cliques():