updated docs

docs/source/api.rst

@@ -128,6 +128,117 @@ API Documentation
         :returns: `list` of `set`\ s
         :raises RuntimeError: if the graph is empty
 
+.. py:class:: NWGraph()
+
+    .. py:attribute:: search_done
+
+        Whether the search has been completed (Readonly)
+
+        :type: `bool`
+
+    .. py:attribute:: n_vertices
+
+        Number of vertices in the graph (Readonly)
+
+        :type: `int`
+
+    .. py:attribute:: n_edges
+
+        Number of edges in the graph (Readonly)
+
+        :type: `int`
+
+    .. py:method:: get_max_clique
+
+        Finds a maximum clique in graph within the given bounds
+
+        :param `float` lower_bound: 
+                set a lower bound on the clique size. default is **1**.
+        :param `float` upper_bound: 
+                set an upper bound on the clique size. default is **65535**.
+        :param `bool` use_heuristic:
+                if `True`\, use the heuristic-based search to obtain a large clique quickly.
+                Good for obtaining an initial lower bound. default is `True`.
+        :param `bool` use_dfs:
+                if `True`\, use the depth-first to obtain the clique. default is `True`\.
+        :returns: the vertices in the maximum clique
+        :rtype: `list`
+        :raises RuntimeError: if the graph is empty or a clique could not be found
+
+    .. py:method:: reset_search
+
+        Reset the search space for `~cliquematch.NWGraph.get_max_clique`.
+
+        :raises RuntimeError: if the graph is empty
+
+    .. py:method:: all_cliques(size)
+
+        Iterate through all cliques of a given size in the `~cliquematch.NWGraph`.
+
+        :param `float` size: size of a clique to search for.
+        :rtype: `~cliquematch.core.NWCliqueIterator`
+        :raises RuntimeError: if the graph is empty
+
+    .. py:method:: get_clique_weight(clique)
+
+        Return the weight of the provided clique.
+
+        :param `list` clique: a clique obtained via `~cliquematch.NWGraph.get_max_clique`.
+        :rtype: `float`
+
+    .. py:staticmethod:: from_edgelist
+
+        Constructs `~cliquematch.NWGraph` instance from the given edge list.
+        Note that vertex indices must start from 1.
+
+        :param `numpy.ndarray` edgelist: shape ``(n,2)``\
+        :param `int` num_vertices: 
+        :returns: the loaded `~cliquematch.NWGraph`
+        :raises RuntimeError: if any value in ``edgelist`` is greater than ``num_vertices``
+        :raises RuntimeError: if value in ``edgelist`` is ``0``
+
+    .. py:staticmethod:: from_matrix
+
+        Constructs `~cliquematch.NWGraph` instance from the given boolean adjacency matrix
+
+        :param `numpy.ndarray` adjmat: `bool` square matrix
+        :returns: the loaded `~cliquematch.NWGraph`
+        :raises RuntimeError: if ``adjmat`` is not square or the edges could not be constructed
+
+    .. py:staticmethod:: from_adjlist
+
+        Constructs `~cliquematch.NWGraph` instance from the given adjacency list.
+        Note that the first element of the list must be an empty `set`\, vertex
+        indices start at 1.
+
+        :param `int` num_vertices:
+        :param `int` num_edges:
+        :param `list` edges: `list` of `set`\s
+        :returns: the loaded `~cliquematch.NWGraph`
+        :raises RuntimeError: if first element in ``edges`` is nonempty, or there are invalid vertices/edges
+
+    .. py:method:: to_edgelist
+
+        Exports `~cliquematch.NWGraph` instance to an edge list
+
+        :returns: ``(n,2)`` `numpy.ndarray` of edges
+        :raises RuntimeError: if the graph is empty
+
+    .. py:method:: to_matrix
+
+        Exports `~cliquematch.NWGraph` instance to a boolean matrix
+
+        :returns: square `numpy.ndarray` of `bool`\ s
+        :raises RuntimeError: if the graph is empty
+
+    .. py:method:: to_adjlist
+
+        Exports `~cliquematch.NWGraph` instance to an adjacency list
+
+        :returns: `list` of `set`\ s
+        :raises RuntimeError: if the graph is empty
+
+
 .. autoclass:: A2AGraph(set1, set2, d1=None, d2=None, is_d1_symmetric=True, is_d2_symmetric=True)
 .. autoclass:: L2LGraph(set1, set2, d1=None, d2=None, is_d1_symmetric=True, is_d2_symmetric=True)
 .. autoclass:: L2AGraph(set1, set2, d1=None, d2=None, is_d1_symmetric=True, is_d2_symmetric=True)
@@ -145,8 +256,12 @@ API Documentation
 
 .. py:class:: CliqueIterator
    
-   A class satisfying the `iter`\/`next` protocol to produces cliques of a given size.
+   A class satisfying the `iter`\/`next` protocol to produces cliques of a given size from a `~cliquematch.Graph`.
 
 .. py:class:: CorrespondenceIterator
    
-   A class satisfying the `iter`\/`next` protocol to produces correspondences of a given size.
+   A class satisfying the `iter`\/`next` protocol to produces correspondences of a given size from a `~cliquematch.Graph`.
+
+.. py:class:: NWCliqueIterator
+   
+   A class satisfying the `iter`\/`next` protocol to produces cliques of a given weight from a `~cliquematch.NWGraph`.

docs/source/conf.py

@@ -21,11 +21,11 @@
 # -- Project information -----------------------------------------------------
 
 project = "cliquematch"
-copyright = "2020, Gautham Venkatasubramanian"
+copyright = "2022, Gautham Venkatasubramanian"
 author = "Gautham Venkatasubramanian"
 
 # The full version, including alpha/beta/rc tags
-release = "2.2.0"
+release = "3.0.0"
 
 
 # -- General configuration ---------------------------------------------------

docs/source/how.rst

@@ -28,7 +28,7 @@ core-number, or the measure used in `cliquematch` all provide such a bound) and
 because bitsets are used for representing branches of the clique search. Thus
 `cliquematch` computes an upper bound for clique size (ie how deep a search can
 go), the maximum bitset space required for a vertex ( :math:`\lceil
-\frac{d_{max}}{32} \rceil` ) and allocates space accordingly. The allocated
+\frac{d_{max}}{64} \rceil` ) and allocates space accordingly. The allocated
 space is reused throughout the search, thus avoiding any heap allocations
 during the most used part of the program. 
 

docs/source/index.rst

@@ -4,28 +4,29 @@
 Finding correspondence via maximum cliques in large graphs
 ----------------------------------------------------------
 
-|pyvers| |license| |travis build| |appveyor build| |doi|
+|pyvers| |license| |ci build| |doi|
 
 The `cliquematch` package aims to do two specific things:
 
 1. Find `maximum cliques`_ in large sparse undirected graphs, as quickly and
-   efficiently as possible. (`cliquematch` uses C++ internally to implement a
-   really fast maximum clique algorithm).
+   efficiently as possible. `cliquematch` v3 also enables finding
+   vertex-weighted maximum cliques via the `~cliquematch.NWGraph` class.
 
 2. Construct large sparse undirected graphs in-memory for the various
    applications of the maximum clique/clique enumeration problem.
 
 That's it. `cliquematch` does not provide a way to modify a large graph once
-it has been loaded, or any other general capability, because: (1) the internal
-data structures are designed to optimize the clique search, (2) sparse graphs
-constructed for applications of the maximum clique problem are rarely modified
-by hand (constructed anew instead), and (3) there are better
-packages (|networkx|_ and |igraph|_) for general graph analysis.
+it has been loaded, or any other general capability, because:
+
+* the internal data structures are designed to optimize the clique search
+* sparse graphs constructed for applications of the maximum clique problem are
+  rarely modified by hand (constructed anew instead)
+* there are better packages (|networkx|_ and |igraph|_) for general graph analysis.
 
 
 .. note::
 
-   This is `cliquematch` v2, which has a simpler API than v1 and also
+   This is `cliquematch` v3, which has a simpler API than v1 and also
    provides the capability of clique enumeration. You view the v1 docs `here`_.
 
 .. toctree::
@@ -42,10 +43,8 @@ packages (|networkx|_ and |igraph|_) for general graph analysis.
    :target: https://www.python.org/download/releases/3.5.0/
 .. |license| image:: https://img.shields.io/github/license/ahgamut/cliquematch
    :target: https://github.com/ahgamut/cliquematch/blob/master/LICENSE
-.. |travis build| image:: https://travis-ci.com/ahgamut/cliquematch.svg?branch=master
-   :target: https://travis-ci.com/ahgamut/cliquematch
-.. |appveyor build| image:: https://ci.appveyor.com/api/projects/status/27r2qy8mbog04bhg?svg=true
-   :target: https://ci.appveyor.com/project/ahgamut/cliquematch
+.. |ci build| image:: https://github.com/ahgamut/cliquematch/actions/workflows/wheels.yml/badge.svg
+   :target: https://github.com/ahgamut/cliquematch/actions
 .. |doi| image:: https://zenodo.org/badge/196044254.svg
    :target: https://zenodo.org/badge/latestdoi/196044254
 .. _maximum cliques: https://en.wikipedia.org/wiki/Clique_(graph_theory)#Definitions

docs/source/setup.rst

@@ -13,7 +13,7 @@ Installing from a wheel
 
 .. code:: bash
 
-    pip install cliquematch>=2.1.0
+    pip install cliquematch>=3.0.0
 
 Installing from source
 ----------------------

src/cliquematch/core/wrap_pygraph.cpp

@@ -84,10 +84,10 @@ void init_pygraph(pybind11::module& m)
              "use_dfs"_a = true)
         .def("get_clique_weight", &pynwgraph::get_clique_weight,
              "calculate the weight of the given clique in this graph", "clique"_a)
-        .def("get_vertex_weights", &pynwgraph::get_all_weights,
-             "return the weights of all the vertices")
         .def("reset_search", &pynwgraph::reset_search,
              "Reset the clique search to try with different parameters")
+        .def("_get_vertex_weights", &pynwgraph::get_all_weights,
+             "return the weights of all the vertices")
         .def("_vertex_neighbors", &pynwgraph::get_vertex_data,
              "Return the neighbors of the given vertex", "v"_a)
         .def("_get_correspondence", &pynwgraph::get_correspondence, "len1"_a, "len2"_a,

tests/nwgraph_test.py

@@ -141,7 +141,7 @@ def test_data(self):
         with pytest.raises(AttributeError):
             G.n_edges = 31
 
-        assert G.get_vertex_weights() == [3.1] * 8
+        assert G._get_vertex_weights() == [3.1] * 8
 
     def test_dfs(self):
         edges = np.array(