{
    "info": {
        "author": "Qiao Chen",
        "author_email": "benechiao@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Operating System :: Unix",
            "Programming Language :: C",
            "Programming Language :: Cython",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3 :: Only",
            "Topic :: Scientific/Engineering",
            "Topic :: Scientific/Engineering :: Mathematics",
            "Topic :: Software Development"
        ],
        "description": "MGMETIS---Mesh & Graph METIS Partitioning\n=========================================\n\n.. image:: https://travis-ci.org/chiao45/mgmetis.svg?branch=master\n    :target: https://travis-ci.org/chiao45/mgmetis\n.. image:: https://img.shields.io/pypi/v/mgmetis.svg?branch=master\n    :target: https://pypi.org/project/mgmetis/\n.. image:: https://img.shields.io/pypi/pyversions/mgmetis.svg?style=flat-square\n    :target: https://pypi.org/project/mgmetis/\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/ambv/black\n\nIntroduction\n------------\n\n*mgmetis* is a mesh and graph Partitioning suite wrapped on top of\n`METIS & ParMETIS <http://glaros.dtc.umn.edu/gkhome/views/metis>`_. It targets\nat intermediate level of package developers who work in, e.g., finite element\nlibraries.\n\n*mgmetis* provides all functionalities from original METIS/ParMETIS via 1) a\n`Cython <https://cython.org/>`_ interface and 2) a native Python interface\nthrough ``ctypes``.\n\nInstallation\n------------\n\n*mgmetis* can be installed via ``pip``, i.e.,\n\n.. code:: console\n\n    $ pip3 install mgmetis --user\n\nIf you have MPI and `mpi4py <https://bitbucket.org/mpi4py/mpi4py/src/master/>`_\ninstalled, then the parallel components will be built automatically. Note that\nmpi4py is **NOT** an installation dependency.\n\nExamples\n--------\n\nIt's worth noting that *mgmetis* simply wraps around original METIS interfaces.\n*mgmetis* doesn't have complicated data structures for graphs and meshes,\neverything is passed in as arrays as per CSR format. The variable names are\npreserved as what they are in the original documentation. For more information,\nplease refer to http://glaros.dtc.umn.edu/gkhome/metis/metis/download and\nhttp://glaros.dtc.umn.edu/gkhome/metis/parmetis/download for METIS and ParMETIS\noriginal documentation PDF files, respectively.\n\nPython Mode\n```````````\n\nFor graph Partitioning, either *multilevel recursive bisection* or\n*multilevel k-way partitioning* methods, the interfaces are exactly the same.\nThe mandatory parameters are ``nparts`` (number of partitions), ``xadj`` (the\nstarting positions of adjacent list) and ``adjncy`` (the compressed adjacent\nlist).\n\nGive a a directed graph based on the following structure::\n\n    0---1---2\n    |   |   |\n    3---4---5\n    |   |   |\n    6---7---8\n\nWe can have the set up a simple graph representation, which looks like\n\n.. code-block:: python\n\n    >>> graph = {\n    ...    0: [1, 3],\n    ...    1: [0, 2, 4],\n    ...    2: [1, 5],\n    ...    3: [0, 4, 6],\n    ...    4: [1, 3, 5, 7],\n    ...    5: [2, 4, 8],\n    ...    6: [3, 7],\n    ...    7: [4, 6, 8],\n    ...    8: [5, 7],\n    ... }\n\n\nWe can then convert it into CSR graph\n\n.. code-block:: python\n\n    >>> xadj = [0]\n    >>> for edges in graph.values():\n    ...     xadj.append(xadj[-1]+len(edges))\n    ...\n    >>> xadj\n    [0, 2, 5, 7, 10, 14, 17, 19, 22, 24]\n    >>> adjncy = [node for edges in graph.values() for node in edges]\n\nThen a partition of 2 with recursive algorithm can be simply done via\n\n.. code-block:: python\n\n    >>> from mgmetis import metis\n    >>> objval, part = metis.part_graph_recursive(2, xadj, adjncy)\n    >>> part\n    array([0, 0, 1, 0, 0, 1, 1, 1, 1])\n\nNotice that the structure in this example can also be viewed as a mesh with 12\nbar cells, of which the user may want to determine a element-wise partition.\n\n.. code-block:: python\n\n    cells = [\n    ...     [0, 1],\n    ...     [1, 2],\n    ...     [3, 4],\n    ...     [4, 5],\n    ...     [6, 7],\n    ...     [7, 8],\n    ...     [0, 3],\n    ...     [1, 4],\n    ...     [2, 5],\n    ...     [3, 6],\n    ...     [4, 7],\n    ...     [5, 8],\n    ... ]\n\nThen, partitoning the mesh into 2 components can be done via `part_mesh_dual`\n\n.. code-block:: python\n\n    >>> objval, epart, npart = metis.part_mesh_dual(2, cells)\n    >>> epart\n    array([0, 0, 0, 1, 1, 1, 0, 0, 1, 0, 1, 1])\n\nFor other supported advanced features, such as weights, please consult the\nMETIS documentation. All the arguments are supported via keyword inputs. Here,\nwe further demonstrate how to customize options, a.k.a. control parameters, in\nMETIS. The parameters in metis are specified via a fixed length 40 integer\narray.\n\n.. code-block:: python\n\n    >>> opts = metis.get_default_options()\n    >>> opts\n    Options([-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,\n             -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,\n             -1, -1, -1, -1, -1, -1, -1, -1], dtype=int32)\n\nIf you are familiar with METIS, you can directly work with the parameters.\n*mgmetis* implements a helper module ``mgmetis.enums`` to help the user work\nwith control parameters. Let's say the user has a Fortran-based index graph\n\n.. code-block:: python\n\n    >>> from mgmetis.enums import OPTION\n    >>> opts[OPTION.NUMBERING] = 1\n    >>> xadj = [x + 1 for x in xadj]\n    >>> adjncy = [x + 1 for x in adjncy]\n    >>> objval, part = metis.part_graph_recursive(2, xadj, adjncy, options=opts)\n    >>> part\n    array([1, 1, 2, 1, 1, 2, 2, 2, 2])\n\n.. note:: *mgmetis* can automatically handle Fortran index.\n\n``ctypes`` Mode\n```````````````\n\nA powerful feature of *mgmetis* is that it allows the user to directly work\nwith the underlying C functions through ``ctypes``. However, by dealing with\nforeign C interfaces, the user needs to explicitly ensure the type consistency.\n\n*mgmetis* supports both 32-bit and 64-bit integer builds of METIS. The original\nMETIS functions all have prefix ``METIS_``, whereas in *mgmetis* ``ctypes``\nmodule, the prefix is trimmed out. Let's see the following example to see how\nto use the ``ctypes`` interface.\n\n.. code-block:: python\n\n    >>> import numpy as np\n    >>> xadj = np.asarray(xadj)  # from list of ints, the dtype is int64\n    >>> adjncy = np.asarray(adjncy)\n    >>> part = np.empty(xadj.size - 1, dtype=int) # output\n    >>> opts = np.assarray(opts, dtype=int)\n\nRecall that the graph partitioning routine takes all arguments as their\nreferences. This can be done via ``ctypes``\n\n.. code-block:: python\n\n    >>> import ctypes as c\n    >>> nv = c.c_int64(part.size)\n    >>> ncon = c.c_int64(1)\n    >>> objval = c.c_int64(0)  # output\n    >>> nparts = c.c_int64(2)\n    >>> xadj_ptr = xadj.ctypes.data_as(c.POINTER(c.c_int64))\n    >>> adj_ptr = adjncy.ctypes.data_as(c.POINTER(c.c_ind64))\n    >>> opts_ptr = opts.ctypes.data_as(c.POINTER(c.c_int64))\n    >>> part_ptr = part.ctypes.data_as(c.POINTER(c.c_int64))  # output address\n\nWe now need to access the ctype interface in *mgmetis*\n\n.. code-block:: python\n\n    >>> from mgmetis.metis import libmetis64  # libmetis for 32bit int\n    >>> libmetis64.PartGraphRecursive(\n    ...     c.byref(nv),\n    ...     c.byref(ncon),\n    ...     xadj_ptr,\n    ...     adj_ptr,\n    ...     None, # NULL\n    ...     None,\n    ...     None,\n    ...     c.byref(nparts),\n    ...     None,\n    ...     None,\n    ...     opts_ptr,\n    ...     c.byref(objval),\n    ...     part_ptr,\n    ... )\n\nFor more details for ``ctypes``, please refer to https://docs.python.org/3.8/library/ctypes.html.\nAlso, take a look at `np.ndarray.ctypes <https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.ctypes.html>`_.\n\nEnable METIS in Cython\n```````````````````````\n\nEach of the METIS routine has a Cython interface, whose naming convention is\nsamilar as it's in ``ctypes`` mode. *mgmetis* resolves the issues regarding\nlinking to METIS. In addition, each of the Cython function is defined with\n``nogil`` specifier.\n\nThe following code shows how to access the ``METIS_PartGraphRecursive``\n\n.. code-block:: cython\n\n    cimport mgmetis.libmetis as metis  # 32 bit\n    # then each of the function in METIS public domain has a Cython interface\n    # without prefix METIS_\n    cdef int ret = metis.PartGraphRecursive(...)\n    if ret != metis.OK:\n        raise ValueError\n\nWhen you compile your Cython code, you don't need to worry about linking to\nMETIS, Python will load the correct symbol in runtime.\n\nWork with MPI\n`````````````\n\nThe native Python mode supports parallel partitioning of a static graph or\nmesh. The underlying routines are:\n\n1. ``ParMETIS_V3_PartKway``,\n2. ``ParMETIS_V3_PartGeomKway``,\n3. ``ParMETIS_V3_PartGeom``, and\n4. ``ParMETIS_V3_PartMeshKway``.\n\nTheir usage is similar to the serial version, please take a look at the unit\ntesting scripts.\n\nA complete support of ParMETIS can be done (for now) via either ``ctypes``\nmode or Cython mode. For ``ctypes`` mode\n\n.. code-block:: python\n\n    from mgmetis.parmetis import libparmetis  # libparmetis64 for 64bit\n    help(libparmetis)\n\nand for the Cython mode\n\n.. code-block:: cython\n\n    cimport mgmetis.parmetis as parmetis  # mgmetis.parmetis64 for 64 bit\n    cdef int ret = parmetis.PartKway(...)\n\nNotice that for Cython mode, you will need to access *mpi4py* Cython interface.\nIt will, then, require you to add its path during specifying ``Extension``, and\nthe compiler needs to be set to *mpicc*.\n\nLicense\n-------\n\n*mgmetis* is considerred as a wrapper of METIS, and it is distributed under MIT\nlicense. Users should also refer to http://glaros.dtc.umn.edu/gkhome/views/metis\nfor the licenses of METIS and ParMETIS.",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/chiao45/mgmetis",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "mgmetis",
        "package_url": "https://pypi.org/project/mgmetis/",
        "platform": "",
        "project_url": "https://pypi.org/project/mgmetis/",
        "project_urls": {
            "Homepage": "https://github.com/chiao45/mgmetis"
        },
        "release_url": "https://pypi.org/project/mgmetis/0.1.0/",
        "requires_dist": null,
        "requires_python": ">=3.6",
        "summary": "METIS partitioner for mesh and graph",
        "version": "0.1.0"
    },
    "last_serial": 5974177,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0cbe67b2b61622c43d9163354b0ecbfa",
                    "sha256": "f71752a147c047c0a5ff896e60e8de7a4a99d9b64ea39cfc7ec8d99f75384c1c"
                },
                "downloads": -1,
                "filename": "mgmetis-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "0cbe67b2b61622c43d9163354b0ecbfa",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6",
                "size": 819659,
                "upload_time": "2019-10-15T00:46:49",
                "url": "https://files.pythonhosted.org/packages/be/38/8f3a6cb7e33b0da2fbf9ad8dbc70de845505c07d24f3fc7c3328f6cde441/mgmetis-0.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0cbe67b2b61622c43d9163354b0ecbfa",
                "sha256": "f71752a147c047c0a5ff896e60e8de7a4a99d9b64ea39cfc7ec8d99f75384c1c"
            },
            "downloads": -1,
            "filename": "mgmetis-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0cbe67b2b61622c43d9163354b0ecbfa",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 819659,
            "upload_time": "2019-10-15T00:46:49",
            "url": "https://files.pythonhosted.org/packages/be/38/8f3a6cb7e33b0da2fbf9ad8dbc70de845505c07d24f3fc7c3328f6cde441/mgmetis-0.1.0.tar.gz"
        }
    ]
}