Ken Watford avatar Ken Watford committed d03714b

Adding documentation

Comments (0)

Files changed (10)

-include *.txt
+include README.rst
+
+
+METIS for Python
+================
+
+Wrapper for the METIS library for partitioning graphs (and other stuff).
+
+This library is unrelated to PyMetis, except that they wrap the same library.
+PyMetis is a Boost Python extension, while this library is pure python and will
+run under PyPy and interpreters with similarly compatible ctypes libraries.
+
+NetworkX_ is recommended for representing graphs for use with this wrapper,
+but it isn't required. Simple adjacency lists are supported as well.
+
+.. _NetworkX: http://networkx.lanl.gov/
+
+The function of primary interest in this module is :func:`part_graph`.
+
+Other objects in the module may be of interest to those looking to 
+mangle their graph datastructures into the required format. Examples
+of this include the :func:`networkx_to_metis` and :func:`adjlist_to_metis` functions.
+These are automatically called by :func:`part_graph`, so there is
+little need to call them manually.
+
+See the BitBucket repository_  for updates and issue reporting.
+
+.. _repository: http://bitbucket.org/kw/metis-python
+
+Installation
+============
+
+It's on PyPI, so installation should be as easy as::
+
+    pip install metis
+          -or-
+    easy_install metis
+
+METIS itself is not included with this wrapper. Get it here_.
+
+.. _here: http://glaros.dtc.umn.edu/gkhome/views/metis
+
+Note that the shared library is needed, and isn't enabled by default
+by the configuration process. Turn it on by issuing::
+
+    make config shared=1
+
+Your operating system's package manager might know about METIS,
+but this wrapper was designed for use with METIS 5. Packages with
+METIS 4 will not work.
+
+This wrapper uses a few environment variables:
+
+.. envvar:: METIS_DLL
+This wrapper uses Python's ctypes module to interface with the METIS
+shared library. If it is unable to automatically locate the library, you
+may specify the full path to the library file in this environment variable.
+
+.. envvar:: METIS_IDXTYPEWIDTH
+.. envvar:: METIS_REALTYPEWIDTH
+The sizes of the :c:type:`idx_t` and :c:type:`real_t` types are not
+easily determinable at runtime, so they can be provided with these 
+environment variables. The default value for each of these (at both compile 
+time and in this library) is 32, but they may be set to 64 if desired. If 
+the values do not match what was used to compile the library, Bad Things(TM) 
+will occur.
+
+Example
+=======
+
+    >>> import networkx as nx
+    >>> import metis 
+    >>> G = metis.example_networkx()
+    >>> (edgecuts, parts) = metis.part_graph(G, 3)
+    >>> colors = ['red','blue','green']
+    >>> for i, p in enumerate(parts):
+    ...     G.node[i]['color'] = colors[p]
+    ... 
+    >>> nx.write_dot(G, 'example.dot') # Requires pydot or pygraphviz
+
+.. graphviz:: example.dot
+

README.txt

-METIS for Python
-================
-
-Wrapper for the METIS library for partitioning graphs (and other stuff).
-
-This library is unrelated to PyMetis, except that they wrap the same library.
-PyMetis is a Boost Python extension, while this library is pure python and will
-run under PyPy and interpreters with similarly compatible ctypes libraries.
-
-The functions of primary interest are:
-
-    `metis.part_graph_kway`
-    `metis.part_graph_recur`
-
-They are also the only objects export by "from metis import *".
-Other objects in the module may be of interest to those looking to 
-mangle their graph datastructures into the required format. Examples
-of this include the `networkx_to_metis` and `adjlist_to_metis` functions.
-These are automatically called by the `part_graph_` functions, so there is
-little need to call them manually.
-
-See the repository_ for updates and issue reporting.
-
-Installation
-============
-
-It's on PyPI, so installation should be as easy as::
-
-    pip install metis
-          -or-
-    easy_install metis
-
-METIS itself is not included with this wrapper. Get it here_.
-
-Note that the shared library is needed, and isn't enabled by default
-by the configuration process. Turn it on by issuing:
-    
-    make config shared=1
-
-Your operating system's package manager might know about METIS,
-but this wrapper was designed for use with METIS 5. Packages with
-METIS 4 will probably not work.
-
-This wrapper uses Python's ctypes module to interface with the METIS
-shared library. If it is unable to automatically locate the library, you
-may specify the full path to the library file in the METIS_DLL environment
-variable.
-
-Additionally, there are a few compile options that you may need to tell
-the wrapper about. The sizes of the "idx_t" and "real_t" types are not
-easily determinable at runtime, so they can be provided with the 
-environment variables METIS_IDXTYPEWIDTH and METIS_REALTYPEWIDTH.
-The default value for each of these (at both compile and in this library)
-is 32, but they may be set to 64 if desired. If the values do not match
-what was used to compile the library, Bad Things™ will occur.
-
-.. _here: http://glaros.dtc.umn.edu/gkhome/views/metis
-.. _repository: http://bitbucket.org/kw/metis-python
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/METISforPython.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/METISforPython.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/METISforPython"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/METISforPython"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+# -*- coding: utf-8 -*-
+#
+# METIS for Python documentation build configuration file, created by
+# sphinx-quickstart on Sun Mar 25 14:22:06 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# 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.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 
+            'sphinx.ext.pngmath', 'sphinx.ext.viewcode', 'sphinx.ext.graphviz']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'METIS for Python'
+copyright = u'2012, Ken Watford'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- 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 = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'METISforPythondoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'METISforPython.tex', u'METIS for Python Documentation',
+   u'Ken Watford', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'metisforpython', u'METIS for Python Documentation',
+     [u'Ken Watford'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'METISforPython', u'METIS for Python Documentation',
+   u'Ken Watford', 'METISforPython', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+strict graph G {
+0 [color=blue];
+1 [color=blue];
+2 [color=blue];
+3 [color=blue];
+4 [color=blue];
+5 [color=blue];
+6 [color=blue];
+7 [color=red];
+8 [color=red];
+9 [color=red];
+10 [color=red];
+11 [color=red];
+12 [color=red];
+13 [color=green];
+14 [color=green];
+15 [color=green];
+16 [color=green];
+17 [color=green];
+18 [color=green];
+0 -- 1;
+0 -- 2;
+0 -- 3;
+0 -- 4;
+4 -- 5;
+5 -- 6;
+6 -- 13;
+6 -- 7;
+7 -- 8;
+8 -- 9;
+8 -- 10;
+8 -- 11;
+8 -- 12;
+13 -- 14;
+14 -- 15;
+15 -- 16;
+15 -- 17;
+15 -- 18;
+}
+.. METIS for Python documentation master file, created by
+   sphinx-quickstart on Sun Mar 25 14:22:06 2012.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. toctree::
+   :maxdepth: 2
+
+.. automodule:: metis
+  :members:
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\METISforPython.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\METISforPython.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end
 """
+METIS for Python
+================
+
 Wrapper for the METIS library for partitioning graphs (and other stuff).
 
 This library is unrelated to PyMetis, except that they wrap the same library.
 PyMetis is a Boost Python extension, while this library is pure python and will
 run under PyPy and interpreters with similarly compatible ctypes libraries.
 
-METIS itself is not included with this wrapper. Get it here:
-   http://glaros.dtc.umn.edu/gkhome/views/metis
+NetworkX_ is recommended for representing graphs for use with this wrapper,
+but it isn't required. Simple adjacency lists are supported as well.
+
+.. _NetworkX: http://networkx.lanl.gov/
+
+The function of primary interest in this module is :func:`part_graph`.
+
+Other objects in the module may be of interest to those looking to 
+mangle their graph datastructures into the required format. Examples
+of this include the :func:`networkx_to_metis` and :func:`adjlist_to_metis` functions.
+These are automatically called by :func:`part_graph`, so there is
+little need to call them manually.
+
+See the BitBucket repository_  for updates and issue reporting.
+
+.. _repository: http://bitbucket.org/kw/metis-python
+
+Installation
+============
+
+It's on PyPI, so installation should be as easy as::
+
+    pip install metis
+          -or-
+    easy_install metis
+
+METIS itself is not included with this wrapper. Get it here_.
+
+.. _here: http://glaros.dtc.umn.edu/gkhome/views/metis
 
 Note that the shared library is needed, and isn't enabled by default
-by the configuration process. Turn it on by issuing:
-    
+by the configuration process. Turn it on by issuing::
+
     make config shared=1
 
 Your operating system's package manager might know about METIS,
 but this wrapper was designed for use with METIS 5. Packages with
 METIS 4 will not work.
 
+This wrapper uses a few environment variables:
+
+.. envvar:: METIS_DLL
 This wrapper uses Python's ctypes module to interface with the METIS
 shared library. If it is unable to automatically locate the library, you
-may specify the full path to the library file in the METIS_DLL environment
-variable.
+may specify the full path to the library file in this environment variable.
 
-Additionally, there are a few compile options that you may need to tell
-the wrapper about. The sizes of the "idx_t" and "real_t" types are not
-easily determinable at runtime, so they can be provided with the 
-environment variables METIS_IDXTYPEWIDTH and METIS_REALTYPEWIDTH.
-The default value for each of these (at both compile and in this library)
-is 32, but they may be set to 64 if desired. If the values do not match
-what was used to compile the library, Bad Things(TM) will occur.
+.. envvar:: METIS_IDXTYPEWIDTH
+.. envvar:: METIS_REALTYPEWIDTH
+The sizes of the :c:type:`idx_t` and :c:type:`real_t` types are not
+easily determinable at runtime, so they can be provided with these 
+environment variables. The default value for each of these (at both compile 
+time and in this library) is 32, but they may be set to 64 if desired. If 
+the values do not match what was used to compile the library, Bad Things(TM) 
+will occur.
 
-The function of primary interest in this module is:
+Example
+=======
 
-    `metis.part_graph`
+    >>> import networkx as nx
+    >>> import metis 
+    >>> G = metis.example_networkx()
+    >>> (edgecuts, parts) = metis.part_graph(G, 3)
+    >>> colors = ['red','blue','green']
+    >>> for i, p in enumerate(parts):
+    ...     G.node[i]['color'] = colors[p]
+    ... 
+    >>> nx.write_dot(G, 'example.dot') # Requires pydot or pygraphviz
 
-It is also the only object currently export by "from metis import *".
-Other objects in the module may be of interest to those looking to 
-mangle their graph datastructures into the required format. Examples
-of this include the `networkx_to_metis` and `adjlist_to_metis` functions.
-These are automatically called by `part_graph`, so there is
-little need to call them manually.
+.. graphviz:: example.dot
 
-See http://bitbucket.org/kw/metis-python for updates and issue reporting.
 """
+# Copyright (c) 2012 Ken Watford
+#
+# Permission is hereby granted, free of charge, to any person 
+# obtaining a copy of this software and associated documentation 
+# files (the "Software"), to deal in the Software without 
+# restriction, including without limitation the rights to use, 
+# copy, modify, merge, publish, distribute, sublicense, and/or 
+# sell copies of the Software, and to permit persons to whom the 
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be 
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 
+# ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
+# CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# tl;dr - MIT license.
 
 __version__ = '0.1a'
 
 except ImportError:
     networkx = None
 
-__all__ = ['part_graph']
+__all__ = ['part_graph', 'networkx_to_metis', 'adjlist_to_metis']
 
 # Sadly, METIS does not currently include any API call to determine
 # the correct datatypes. So we either have to guess, let the user tell
     This is the default error checker when using _wrapdll
     """
     if result != METIS_OK:
-        if error == METIS_ERROR_INPUT: raise METIS_InputError
-        if error == METIS_ERROR_MEMORY: raise METIS_MemoryError
-        if error == METIS_ERROR: raise METIS_OtherError
+        if result == METIS_ERROR_INPUT: raise METIS_InputError
+        if result == METIS_ERROR_MEMORY: raise METIS_MemoryError
+        if result == METIS_ERROR: raise METIS_OtherError
         raise RuntimeError("Error raising error: Bad error.") # lolwut
     return result
 
     'nvtxs ncon xadj adjncy vwgt vsize adjwgt')
 
 def networkx_to_metis(G):
-    """ Convert NetworkX graph into something METIS can consume
+    """
+    Convert NetworkX graph into something METIS can consume
     The graph may specify weights and sizes using the following
     graph attributes:
 
-      edge_weight_attr
-      node_weight_attr
-      node_size_attr
+    * ``edge_weight_attr``
+    * ``node_weight_attr`` (multiple names allowed)
+    * ``node_size_attr``
+
+    For example::
+
+        >>> G.edge[0][1]['weight'] = 3
+        >>> G.node[0]['quality'] = 5
+        >>> G.node[0]['specialness'] = 8
+        >>> G.graph['edge_weight_attr'] = 'weight'
+        >>> G.graph['node_weight_attr'] = ['quality', 'specialness']
 
     If node_weight_attr is a list instead of a string, then multiple
     node weight labels can be provided. 
 
-    All weights must be integer values. If a attr label is specified but 
+    All weights must be integer values. If an attr label is specified but 
     a node/edge is missing that attribute, it defaults to 1.
+
+    If a graph attribute is not provided, no defaut is used. That is, if
+    ``edge_weight_attr`` is not set, then ``'weight'`` is not used as the
+    default, and the graph will appear unweighted to METIS.
     """
     n = G.number_of_nodes()
     m = G.number_of_edges()
     Rudimentary adjacency list converter.
     Primarily of use if you don't have or don't want to use NetworkX.
 
-    `adjlist` is a list of tuples. Each list element represents a node or vertex
-    in the graph. Each item in the tuples represents an edge. These items may be 
-    single integers representing neighbor index, or they may be an (index, weight)
-    tuple if you want weighted edges. Default weight is 1 for missing weights.
-
-    The graph must be undirected, and each edge must be represented twice (once for
-    each node). The weights should be identical, if provided.
-
-    `nodew` is a list of node weights, and must be the same size as `adjlist` if given.
-    If desired, the elements of `nodew` may be tuples of the same size (>= 1) to provided
-    multiple weights for each node. 
-
-    `nodesz` is a list of node sizes. These are relevant when doing volume-based
-    partitioning. 
+    :param adjlist: A list of tuples. Each list element represents a node or vertex
+      in the graph. Each item in the tuples represents an edge. These items may be 
+      single integers representing neighbor index, or they may be an (index, weight)
+      tuple if you want weighted edges. Default weight is 1 for missing weights.
+      
+      The graph must be undirected, and each edge must be represented twice (once for
+      each node). The weights should be identical, if provided.
+    :param nodew: is a list of node weights, and must be the same size as `adjlist` if given.
+      If desired, the elements of `nodew` may be tuples of the same size (>= 1) to provided
+      multiple weights for each node. 
+    :param nodesz: is a list of node sizes. These are relevant when doing volume-based
+      partitioning. 
 
     Note that all weights and sizes must be non-negative integers.
     """
     the objective function that was minimized (either the edge cuts
     or the total volume).
 
-    `graph` may be a NetworkX graph, an adjacency list, or a METIS_Graph 
-    named tuple. To use the named tuple approach, you'll need to
-    read the METIS manual for the meanings of the fields.
+    :param graph: may be a NetworkX graph, an adjacency list, or a :class:`METIS_Graph`
+      named tuple. To use the named tuple approach, you'll need to
+      read the METIS manual for the meanings of the fields.
+  
+      See :func:`networkx_to_metis` for help and details on how the
+      graph is converted and how node/edge weights and sizes can
+      be specified.
+  
+      See :func:`adjlist_to_metis` for information on the use of adjacency lists.
+      The extra ``nodew`` and ``nodesz`` keyword arguments of that function may be given 
+      directly to this function and will be forwarded to the converter. 
+      Alternatively, a dictionary can be provided as ``graph`` and its items
+      will be passed as keyword arguments.
+    :param nparts: The target number of partitions. You might get fewer.
+    :param tpwgts: Target partition weights. For each partition, there should
+      be one (float) weight for each node constraint. That is, if `nparts` is 3 and 
+      each node of the graph has two weights, then tpwgts might look like this::
+  
+        [(0.5, 0.1), (0.25, 0.8), (0.25, 0.1)]
 
-    See `networkx_to_metis` for help and details on how the
-    graph is converted and how node/edge weights and sizes can
-    be specified.
+      This list may be provided flattened. The internal tuples are for convenience.
+      The partition weights for each constraint must sum to 1. 
+    :param ubvec: The load imalance tolerance for each node constraint. Should be
+      a list of floating point values each greater than 1.
 
-    See `adjlist_to_metis` for information on the use of adjacency lists.
-    The extra `nodew` and `nodesz` options of that function may be given 
-    directly to this function and will be forwarded to the converter. 
-    Alternatively, a dictionary can be provided as `graph` and its items
-    will be passed as keyword arguments.
-
-    `nparts` is the target number of partitions. You might get fewer.
-
-    You probably won't need to specify `tpwgts` and `ubvec`, but if 
-    you do, you'll read the METIS manual to see what they are. Any
-    sequence type with floats may be provided so long as the number of
-    elements is correct. If a ctypes Array is provided, it must be the
-    correct type (`metis.real_t`). 
+    :param recursive: Determines whether the partitioning should be done by 
+      direct k-way cuts or by a series of recursive cuts. These correspond to 
+      :c:func:`METIS_PartGraphKway` and :c:func:`METIS_PartGraphRecursive` in
+      METIS's C API.
 
     Any additional METIS options may be specified as keyword parameters.
 
-    For k-way clustering, the appropriate options are:
+    For k-way clustering, the appropriate options are::
 
-       objtype   = 'cut' or 'vol' 
-       ctype     = 'rm' or 'shem' 
-       iptype    = 'grow', 'random', 'edge', 'node'
-       rtype     = 'fm', 'greedy', 'sep2sided', 'sep1sided'
-       ncuts     = integer, number of cut attempts (default = 1)
-       niter     = integer, number of iterations (default = 10)
-       ufactor   = integer, maximum load imbalance of (1+x)/1000
-       minconn   = bool, minimize degree of subdomain graph
-       contig    = bool, force contiguous partitions
-       seed      = integer, RNG seed
-       numbering = 0 (C-style) or 1 (Fortran-style) indices
-       dbglvl    = Debug flag bitfield
+        objtype   = 'cut' or 'vol' 
+        ctype     = 'rm' or 'shem' 
+        iptype    = 'grow', 'random', 'edge', 'node'
+        rtype     = 'fm', 'greedy', 'sep2sided', 'sep1sided'
+        ncuts     = integer, number of cut attempts (default = 1)
+        niter     = integer, number of iterations (default = 10)
+        ufactor   = integer, maximum load imbalance of (1+x)/1000
+        minconn   = bool, minimize degree of subdomain graph
+        contig    = bool, force contiguous partitions
+        seed      = integer, RNG seed
+        numbering = 0 (C-style) or 1 (Fortran-style) indices
+        dbglvl    = Debug flag bitfield
 
-    For recursive clustering, the appropraite options are:
+    For recursive clustering, the appropraite options are::
 
-       ctype     = 'rm' or 'shem' 
-       iptype    = 'grow', 'random', 'edge', 'node'
-       rtype     = 'fm', 'greedy', 'sep2sided', 'sep1sided'
-       ncuts     = integer, number of cut attempts (default = 1)
-       niter     = integer, number of iterations (default = 10)
-       ufactor   = integer, maximum load imbalance of (1+x)/1000
-       seed      = integer, RNG seed
-       numbering = 0 (C-style) or 1 (Fortran-style) indices
-       dbglvl    = Debug flag bitfield
+        ctype     = 'rm' or 'shem' 
+        iptype    = 'grow', 'random', 'edge', 'node'
+        rtype     = 'fm', 'greedy', 'sep2sided', 'sep1sided'
+        ncuts     = integer, number of cut attempts (default = 1)
+        niter     = integer, number of iterations (default = 10)
+        ufactor   = integer, maximum load imbalance of (1+x)/1000
+        seed      = integer, RNG seed
+        numbering = 0 (C-style) or 1 (Fortran-style) indices
+        dbglvl    = Debug flag bitfield
 
     See the METIS manual for specific meaning of each option.
     """
             graph = adlist_to_metis(**graph)
 
     if tpwgts and not isinstance(tpwgts, ctypes.Array):
+        if isinstance(tpwgts[0], (tuple, list)):
+            tpwgts = reduce(op.add, tpwgts)   
         tpwgts = (real_t*len(tpwgts))(*tpwgts)
     if ubvec and not isinstance(ubvec, ctypes.Array):
         ubvec = (real_t*len(ubvect))(*ubvec)
+
+    if tpwgts: assert len(tpgwgts) == nparts * graph.ncon
+    if ubvec: assert len(ubvec) == graph.ncon
+
     nparts_var = idx_t(nparts)
 
     objval = idx_t()
     
     return objval.value, list(partition)
 
+def example_adjlist():
+    return [[1, 2, 3, 4], [0], [0], [0], [0, 5], [4, 6], [13, 5, 7], 
+            [8, 6], [9, 10, 11, 12, 7], [8], [8], [8], [8], [14, 6], [13, 15],
+            [16, 17, 18, 14], [15], [15], [15]]
+
+def example_networkx():
+    G = networkx.Graph()
+    G.add_star([0,1,2,3,4])
+    G.add_path([4,5,6,7,8])
+    G.add_star([8,9,10,11,12])
+    G.add_path([6,13,14,15])
+    G.add_star([15,16,17,18])
+    return G
+
 def test():
-    adjlist = [[1, 2, 3, 4], [0], [0], [0], [0, 5], [4, 6], [5, 7, 13], 
-                [8, 6], [7], [10, 11, 12], [9], [9], [9], [6, 14], [13, 15],
-                [14, 16, 17, 18], [15], [15], [15]] 
+    adjlist = example_adjlist()
+
     print "Testing k-way cut"
     cuts, parts = part_graph(adjlist, 3, recursive=False, dbglvl=METIS_DBG_ALL)
     assert cuts == 2
 
     print "Testing recursive cut"
     cuts, parts = part_graph(adjlist, 3, recursive=True, dbglvl=METIS_DBG_ALL)
-    assert cuts <= 3
+    assert cuts == 2
     assert set(parts) == set([0,1,2])
 
     if networkx:
         print "Testing with NetworkX"
-        G = networkx.Graph()
-        G.add_star([0,1,2,3,4])
-        G.add_path([4,5,6,7,8])
-        G.add_star([9,10,11,12])
-        G.add_path([6,13,14,15])
-        G.add_star([15,16,17,18])
-        cuts, parts = part_graph(adjlist, 3)
+        G = example_networkx()
+        cuts, parts = part_graph(G, 3)
         assert cuts == 2
         assert set(parts) == set([0,1,2])
 
-    print "METIS appears to be working."
+    print "METIS appears to be working."    
 
+
 from distutils.command.sdist import sdist
 from subprocess import Popen, PIPE
 
-from metis import __version__
+
 
 class sdist_hg(sdist):
     user_options = sdist.user_options + [
             rev = "deadbeef"
         return rev
 
+
+import metis
+readmefile = open('README.rst', 'wt')
+readmefile.write(metis.__doc__)
+readmefile.close()
+
 setup(
     name='metis',
-    version=__version__,
+    version=metis.__version__,
     author="Ken Watford",
     author_email="kwatford@gmail.com",
     url="https://bitbucket.org/kw/metis-python",
     py_modules=['metis'],
     license='MIT',
     description="METIS wrapper using ctypes",    
-    long_description=open('README.txt').read(),
+    long_description= metis.__doc__,
     cmdclass={'sdist': sdist_hg},
     classifiers = [
         'Development Status :: 3 - Alpha',
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.