diff --git a/.gitignore b/.gitignore index 98669460..519d747d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,14 @@ build +_build dist dwave_networkx.egg-info *.pyc venv/ -docs/reference/generated/ -docs/reference/algorithms/generated/ -docs/reference/drawing/generated/ +docs/generated/ +docs/algorithms/generated/ +docs/drawing/generated/ htmlcov/ .coverage diff --git a/README.rst b/README.rst index 930e2869..feece838 100644 --- a/README.rst +++ b/README.rst @@ -7,48 +7,42 @@ .. image:: https://circleci.com/gh/dwavesystems/dwave-networkx.svg?style=svg :target: https://circleci.com/gh/dwavesystems/dwave-networkx -D-Wave NetworkX -=============== +============== +dwave-networkx +============== -.. index-start-marker +.. start_dnx_about -D-Wave NetworkX is an extension of `NetworkX `_\ ---a +dwave-networkx is an extension of `NetworkX `_\ ---a Python language package for exploration and analysis of networks and network -algorithms---for users of D-Wave quantum computers. It provides tools for working -with Quantum Processing Unit (QPU) topology graphs, such as the Pegasus used on -the Advantage\ |TM| system, and implementations of graph-theory algorithms on D-Wave -quantum computers and other binary quadratic model samplers. - -.. |TM| replace:: :sup:`TM` +algorithms---for users of D-Wave quantum computers. It provides tools for +working with quantum processing unit (QPU) topology graphs, such as the Pegasus +used on the Advantage\ :sup:`TM` quantum computer, and implementations of +graph-theory algorithms on D-Wave quantum computers and other binary quadratic +model (BQM) samplers. This example generates a Pegasus graph of the size used by Advantage QPUs. >>> import dwave_networkx as dnx >>> graph = dnx.pegasus_graph(16) -See the documentation for more examples. - -.. index-end-marker +.. end_dnx_about Installation ============ -.. installation-start-marker - **Installation from PyPi:** .. code-block:: bash - pip install dwave_networkx + pip install dwave_networkx **Installation from source:** .. code-block:: bash - pip install -r requirements.txt - python setup.py install - -.. installation-end-marker + pip install -r requirements.txt + python setup.py install License ======= @@ -58,5 +52,5 @@ Released under the Apache License 2.0. Contributing ============ -Ocean's `contributing guide `_ +Ocean's `contributing guide `_ has guidelines for contributing to Ocean packages. diff --git a/docs/LICENSE.txt b/docs/LICENSE.txt deleted file mode 120000 index 4ab43736..00000000 --- a/docs/LICENSE.txt +++ /dev/null @@ -1 +0,0 @@ -../LICENSE.txt \ No newline at end of file diff --git a/docs/algorithms.rst b/docs/algorithms.rst new file mode 100644 index 00000000..fdeebbe9 --- /dev/null +++ b/docs/algorithms.rst @@ -0,0 +1,317 @@ +.. _dnx_algorithms: + +========== +Algorithms +========== + +Implementations of graph-theory algorithms on the D-Wave system and other +binary quadratic model samplers. + +.. currentmodule:: dwave_networkx + +.. _dnx_canonicalization: + +Canonicalization +================ + +.. automodule:: dwave_networkx.algorithms.canonicalization + +.. autosummary:: + :toctree: generated/ + + canonical_chimera_labeling + +.. _dnx_clique: + +Clique +====== + +A clique in an undirected graph G = (V, E) is a subset of the vertex set such +that for every two vertices in C there exists an edge connecting the two. + +.. figure:: _images/clique.png + :name: Cover + :alt: image + :align: center + :scale: 40 % + +.. automodule:: dwave_networkx.algorithms.clique + +.. autosummary:: + :toctree: generated/ + + maximum_clique + clique_number + is_clique + +.. _dnx_coloring: + +Coloring +======== + +Graph coloring is the problem of assigning a color to the vertices of a graph in +a way that no adjacent vertices have the same color. + +Example +------- + +The map-coloring problem is to assign a color to each region of a map +(represented by a vertex on a graph) such that any two regions sharing a border +(represented by an edge of the graph) have different colors. + +.. figure:: _images/Problem_MapColoring.png + :name: Problem_MapColoringColoring + :alt: image + :align: center + :scale: 70 % + + Coloring a map of Canada with four colors. + +.. automodule:: dwave_networkx.algorithms.coloring + +.. autosummary:: + :toctree: generated/ + + is_vertex_coloring + min_vertex_color + min_vertex_color_qubo + vertex_color + vertex_color_qubo + +.. _dnx_cover: + +Cover +===== + +Vertex covering is the problem of finding a set of vertices such that all the +edges of the graph are incident to at least one of the vertices in the set. + +.. figure:: _images/Cover.png + :name: CoverCover + :alt: image + :align: center + :scale: 40 % + + Cover for a Chimera unit cell: the nodes of both the blue set of vertices + (the horizontal tile of the Chimera unit cell) and the red set (vertical + tile) connect to all 16 edges of the graph. + +.. automodule:: dwave_networkx.algorithms.cover + +.. autosummary:: + :toctree: generated/ + + is_vertex_cover + min_weighted_vertex_cover + min_vertex_cover + +.. _dnx_elimination_ordering: + +Elimination Ordering +==================== + +Many algorithms for NP-hard problems are exponential in treewidth. However, +finding a lower bound on treewidth is in itself NP-complete. [Gog2004]_ +describes a branch-and-bound algorithm for computing the treewidth of an +undirected graph by searching in the space of *perfect elimination ordering* of +vertices of the graph. + +A *clique* of a graph is a fully-connected subset of vertices; that is, every +pair of vertices in the clique share an edge. A *simplicial* vertex is one +whose neighborhood induces a clique. A perfect elimination ordering is an +ordering of vertices :math:`1..n` such that any vertex :math:`i` is simplicial +for the subset of vertices :math:`i..n`. + +.. automodule:: dwave_networkx.algorithms.elimination_ordering + +.. autosummary:: + :toctree: generated/ + + chimera_elimination_order + elimination_order_width + is_almost_simplicial + is_simplicial + max_cardinality_heuristic + minor_min_width + min_fill_heuristic + min_width_heuristic + pegasus_elimination_order + treewidth_branch_and_bound + +.. _dnx_markov: + +Markov Networks +=============== + +.. automodule:: dwave_networkx.algorithms.markov + +.. autosummary:: + :toctree: generated/ + + sample_markov_network + markov_network_bqm + +.. _dnx_matching: + +Matching +======== + +A matching is a subset of graph edges in which no vertex occurs more than once. + +.. figure:: _images/Match.png + :name: Matching + :alt: image + :align: center + :scale: 40 % + + A matching for a Chimera unit cell: no vertex is incident to more than one + edge in the set of blue edges + +.. automodule:: dwave_networkx.algorithms.matching + +.. autosummary:: + :toctree: generated/ + + matching_bqm + maximal_matching_bqm + min_maximal_matching_bqm + min_maximal_matching + +.. _dnx_maximum_cut: + +Maximum Cut +=========== + +A maximum cut is a subset of a graph's vertices such that the number of edges +between this subset and the remaining vertices is as large as possible. + +.. figure:: _images/MaxCut.png + :name: Cut + :alt: image + :align: center + :scale: 60 % + + Maximum cut for a Chimera unit cell: the blue line around the subset of + nodes {4, 5, 6, 7} cuts 16 edges; adding or removing a node decreases the + number of edges between the two complementary subsets of the graph. + +.. automodule:: dwave_networkx.algorithms.max_cut + +.. autosummary:: + :toctree: generated/ + + maximum_cut + weighted_maximum_cut + +.. _dnx_independent_set: + +Independent Set +=============== + +An independent set is a set of a graph's vertices with no edge connecting any of +its member pairs. + +.. figure:: _images/Cover.png + :name: CoverIndependentSet + :alt: image + :align: center + :scale: 40 % + + Independent sets for a Chimera unit cell: the nodes of both the blue set of + vertices (the horizontal tile of the Chimera unit cell) and the red set + (vertical tile) are independent sets of the graph, with no blue node + adjacent to another blue node and likewise for red nodes. + +.. automodule:: dwave_networkx.algorithms.independent_set + +.. autosummary:: + :toctree: generated/ + + maximum_weighted_independent_set + maximum_independent_set + is_independent_set + +Helper Functions +---------------- + +.. autosummary:: + :toctree: generated/ + + maximum_weighted_independent_set_qubo + +.. _dnx_partitioning: + +Partitioning +============ + +A `k`-partition consists of `k` disjoint and equally sized subsets of a graph's +vertices such that the total number of edges between nodes in distinct subsets +is as small as possible. + +.. figure:: _images/Partitioning.png + :name: Partition + :alt: image + :align: center + :scale: 60 % + + A 2-partition for a simple graph: the nodes in blue are in the '0' subset, + and the nodes in red are in the '1' subset. There are no other arrangements + with fewer edges between two equally sized subsets. + +.. automodule:: dwave_networkx.algorithms.partition + +.. autosummary:: + :toctree: generated/ + + partition + +.. _dnx_social: + +Social +====== + +A signed social network graph is a graph whose signed edges represent +friendly/hostile interactions between vertices. + +.. figure:: _images/Social.png + :name: Social + :alt: image + :align: center + :scale: 80 % + + A signed social graph for three nodes, where Eve and Bob are friendly with + each other and hostile to Alice. This network is balanced because it can be + cleanly divided into two subsets, {Bob, Eve} and {Alice}, with friendly + relations within each subset and only hostile relations between the subsets. + +.. automodule:: dwave_networkx.algorithms.social + +.. autosummary:: + :toctree: generated/ + + structural_imbalance + structural_imbalance_ising + +.. _dnx_traveling_salesperson: + +Traveling Salesperson +===================== + +A traveling salesperson route is an ordering of the vertices in a complete +weighted graph. + +.. figure:: _images/tsp.png + :name: TSP_route + :alt: image + :align: center + :scale: 80 % + + A traveling salesperson route of [2, 1, 0, 3]. + +.. automodule:: dwave_networkx.algorithms.tsp + +.. autosummary:: + :toctree: generated/ + + traveling_salesperson + traveling_salesperson_qubo \ No newline at end of file diff --git a/docs/api_ref.rst b/docs/api_ref.rst new file mode 100644 index 00000000..9c2f59a7 --- /dev/null +++ b/docs/api_ref.rst @@ -0,0 +1,14 @@ +.. _dnx_api_ref: + +============= +API Reference +============= + +.. toctree:: + :maxdepth: 2 + + algorithms + drawing + generators + utilities + default_sampler \ No newline at end of file diff --git a/docs/bibliography.rst b/docs/bibliography.rst deleted file mode 100644 index ede254b0..00000000 --- a/docs/bibliography.rst +++ /dev/null @@ -1,37 +0,0 @@ -Bibliography -============ - -.. [Boo2019] - Boothby K., P. Bunyk, J. Raymond and A. Roy. - Next-Generation Topology of D-Wave Quantum Processors. 2019. - https://arxiv.org/abs/2003.00133 - -.. [Boo2021] - Boothby K., J. Raymond and A. D. King. - Zephyr Topology of D-Wave Quantum Processors. September 22, 2021. - https://dwavesys.com/media/fawfas04/14-1056a-a_zephyr_topology_of_d-wave_quantum_processors.pdf - -.. [Dah2013] - Dahl E.D. - Programming the D-Wave: Map Coloring Problem. November 2013. - https://www.dwavesys.com/media/htfgw5bk/map-coloring-wp2.pdf - -.. [Gog2004] - Gogate V. and R. Dechter. - A Complete Anytime Algorithm for Treewidth. - UAI '04: Proceedings of the 20th conference on Uncertainty in artificial - intelligence. Pages 201 - 208. July 7, 2004. - https://arxiv.org/abs/1207.4109 - -.. [Luc2014] - Lucas A. - Ising formulations of many NP problems. - Frontiers in Physics, Volume 2, Article 5. February 11, 2014. - -.. [Ray2023] - Raymond J., R. Stevanovic, W. Bernoudy, K. Boothby, C. C. McGeoch, A. J. - Berkley, P. Farré, J. Pasvolsky, and A. D. King. - Hybrid quantum annealing for larger-than-QPU lattice-structured problems. - ACM Transactions on Quantum Computing, Volume 4, Issue 3 Article No.: 17, - Pages 1 - 30. April 8, 2023 - https://arxiv.org/abs/2202.03044 diff --git a/docs/conf.py b/docs/conf.py index f6efe2e5..c3649ce3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,33 +1,17 @@ -# -*- coding: utf-8 -*- -# # DWaveNetworkX documentation build configuration file, created by # sphinx-quickstart on Wed Jul 26 10:55:26 2017. # -# 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. +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -# 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('.')) sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) # -- General configuration ------------------------------------------------ -# import sphinx -# if sphinx.__version__ # can check here -# 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.autosummary', 'sphinx.ext.autodoc', @@ -43,14 +27,8 @@ autosummary_generate = True -# templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst'] -# The master toctree document. master_doc = 'index' # General information about the project. @@ -58,28 +36,14 @@ copyright = u'2017, D-Wave Systems Inc' author = u'D-Wave Systems Inc' -# 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. -# import dwave_networkx -# The short X.Y version. version = dwave_networkx.__version__ -# The full version, including alpha/beta/rc tags. release = dwave_networkx.__version__ -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - +language = 'en' add_module_names = False -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path + exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'sdk_index.rst'] linkcheck_retries = 2 @@ -88,10 +52,8 @@ r'https://cloud.dwavesys.com/leap', # redirects, many checks ] -# The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True modindex_common_prefix = ['dwave_networkx.'] @@ -102,113 +64,21 @@ import networkx as nx """ - # -- Options for HTML output ---------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -import sphinx_rtd_theme -html_theme = 'sphinx_rtd_theme' -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# 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 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'] - -def setup(app): - app.add_css_file('cookie_notice.css') - app.add_js_file('cookie_notice.js') - app.add_config_value('target', 'repo', 'env') - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'DWaveNetworkXdoc' - - -# -- 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': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', +html_theme = 'pydata_sphinx_theme' +html_theme_options = { + "collapse_navigation": True, + "show_prev_next": False, } +html_sidebars = {"**": ["search-field", "sidebar-nav-bs"]} # remove ads -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'DWaveNetworkX.tex', u'DWaveNetworkX Documentation', - u'D-Wave Systems Inc', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'dwavenetworkx', u'DWaveNetworkX Documentation', - [author], 1) -] - - -# -- 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 = [ - (master_doc, 'DWaveNetworkX', u'DWaveNetworkX Documentation', - author, 'DWaveNetworkX', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ---------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project -epub_author = author -epub_publisher = author -epub_copyright = copyright - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - - -# Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'python': ('https://docs.python.org/3', None), 'networkx': ('https://networkx.github.io/documentation/stable/', None), - 'qbsolv': ('https://docs.ocean.dwavesys.com/projects/qbsolv/en/latest/', None), - 'oceandocs': ('https://docs.ocean.dwavesys.com/en/latest/', None), - 'sysdocs_gettingstarted': ('https://docs.dwavesys.com/docs/latest/', None)} + 'dwave': ('https://docs.dwavequantum.com/en/latest/', None), + } + +# global substitutions +rst_epilog = """ +.. |dwave_short| unicode:: D-Wave +""" \ No newline at end of file diff --git a/docs/default_sampler.rst b/docs/default_sampler.rst new file mode 100644 index 00000000..9540c0d2 --- /dev/null +++ b/docs/default_sampler.rst @@ -0,0 +1,19 @@ +.. _dnx_default_sampler: + +=============== +Default sampler +=============== + +.. currentmodule:: dwave_networkx.default_sampler + +.. automodule:: dwave_networkx.default_sampler + +Functions +========= + +.. autosummary:: + :toctree: generated/ + + set_default_sampler + unset_default_sampler + get_default_sampler diff --git a/docs/reference/drawing.rst b/docs/drawing.rst similarity index 92% rename from docs/reference/drawing.rst rename to docs/drawing.rst index 5445a724..74b00105 100644 --- a/docs/reference/drawing.rst +++ b/docs/drawing.rst @@ -1,15 +1,16 @@ -.. _drawing: +.. _dnx_drawing: -******* +======= Drawing -******* +======= -Tools to visualize topologies of D-Wave QPUs and weighted :term:`graph` problems on them. +Tools to visualize topologies of D-Wave QPUs and weighted :term:`graph` problems +on them. .. currentmodule:: dwave_networkx Chimera Graph Functions ------------------------ +======================= .. automodule:: dwave_networkx.drawing.chimera_layout @@ -23,7 +24,7 @@ Chimera Graph Functions draw_chimera_yield Example -~~~~~~~ +------- This example uses the :func:`.chimera_layout()` function to show the positions of nodes of a simple 5-node NetworkX graph in a Chimera lattice. It then uses the @@ -53,7 +54,7 @@ positions on a Chimera unit cell. >>> plt.show() >>> # matplotlib commands to add labels to graphic not shown -.. figure:: ../_images/chimera_layout_0-rightside.png +.. figure:: _images/chimera_layout_0-rightside.png :align: center :name: chimera_layout_0-rightside :scale: 60 % @@ -64,7 +65,7 @@ positions on a Chimera unit cell. Pegasus Graph Functions ------------------------ +======================= .. automodule:: dwave_networkx.drawing.pegasus_layout @@ -78,7 +79,7 @@ Pegasus Graph Functions pegasus_node_placer_2d Example -~~~~~~~ +------- This example uses the :func:`.draw_pegasus()` function to show the positions of nodes of a simple 5-node graph on a small Pegasus lattice. @@ -97,7 +98,7 @@ of nodes of a simple 5-node graph on a small Pegasus lattice. edge_color='b', width=3, ax=axes) >>> plt.show() -.. figure:: ../_images/pegasus_layout_h_on_g.png +.. figure:: _images/pegasus_layout_h_on_g.png :align: center :name: pegasus_layout_h_on_g.png :scale: 60 % @@ -107,7 +108,7 @@ of nodes of a simple 5-node graph on a small Pegasus lattice. which is rendered in a cross layout. Zephyr Graph Functions ----------------------- +====================== .. automodule:: dwave_networkx.drawing.zephyr_layout @@ -121,7 +122,7 @@ Zephyr Graph Functions zephyr_node_placer_2d Example -~~~~~~~ +------- This example uses the :func:`.draw_zephyr_embedding` function to show the positions of a five-node clique on a small Zephyr graph. @@ -138,7 +139,7 @@ of a five-node clique on a small Zephyr graph. >>> plt.ion() >>> dnx.draw_zephyr_embedding(G, embedding, show_labels=True) -.. figure:: ../_images/zephyr_embedding_5clique.png +.. figure:: _images/zephyr_embedding_5clique.png :align: center :name: zephyr_embedding_5clique.png :scale: 60 % diff --git a/docs/reference/generators.rst b/docs/generators.rst similarity index 89% rename from docs/reference/generators.rst rename to docs/generators.rst index 9be9df2b..f70fe3bd 100644 --- a/docs/reference/generators.rst +++ b/docs/generators.rst @@ -1,14 +1,15 @@ -.. _generators_dnx: +.. _dnx_generators: +================ Graph Generators -**************** +================ Generators for graphs, such the graphs (topologies) of D-Wave System QPUs. .. currentmodule:: dwave_networkx D-Wave Systems --------------- +============== .. autosummary:: :toctree: generated/ @@ -17,10 +18,8 @@ D-Wave Systems pegasus_graph zephyr_graph - - Example -~~~~~~~ +------- This example uses the the `chimera_graph()` function to create a Chimera lattice of size (1, 1, 4), which is a single unit cell in Chimera topology, and @@ -42,7 +41,7 @@ the `find_chimera()` function to determine the Chimera indices. 6: (0, 0, 1, 2), 7: (0, 0, 1, 3)} -.. figure:: ../_images/find_chimera-unitcell.png +.. figure:: _images/find_chimera-unitcell.png :align: center :name: find_chimera-unitcell :scale: 30 % @@ -51,7 +50,7 @@ the `find_chimera()` function to determine the Chimera indices. Indices of a Chimera unit cell found by creating a lattice of size (1, 1, 4). Toruses -------- +======= .. autosummary:: :toctree: generated/ @@ -59,9 +58,9 @@ Toruses chimera_torus pegasus_torus zephyr_torus - + Other Graphs ------------- +============ .. autosummary:: :toctree: generated/ diff --git a/docs/index.rst b/docs/index.rst index ac7fc315..9e0fe511 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,68 +1,43 @@ -.. -*- coding: utf-8 -*- - .. _index_dnx: ============== dwave-networkx ============== -.. include:: README.rst - :start-after: index-start-marker - :end-before: index-end-marker - -Documentation -------------- - -.. only:: html - - :Release: |version| - :Date: |today| - -.. note:: This documentation is for the latest version of - `dwave-networkx `_. - Documentation for the version currently installed by - `dwave-ocean-sdk `_ - is here: :std:doc:`dwave-networkx `. - -.. sdk-start-marker - -.. toctree:: - :maxdepth: 1 - - intro - reference/index - bibliography - -.. sdk-end-marker - -.. toctree:: - :caption: Code - :maxdepth: 1 - - Source - installation - license .. toctree:: - :caption: D-Wave's Ocean Software + :caption: Reference documentation for dwave-networkx: :maxdepth: 1 - Ocean Home - Ocean Documentation - Ocean Glossary + api_ref -.. toctree:: - :caption: D-Wave - :maxdepth: 1 - D-Wave - Leap - D-Wave System Documentation +About dwave-networkx +==================== -Indices and tables ------------------- - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` -* `Glossary `_ \ No newline at end of file +.. include:: README.rst + :start-after: start_dnx_about + :end-before: end_dnx_about + +Functions such as :func:`.draw_pegasus` provide easy visualization for +:term:`Pegasus` graphs while functions such as +:func:`~dwave_networkx.algorithms.max_cut.maximum_cut` or +:func:`~dwave_networkx.algorithms.cover.min_vertex_cover` provide graph +algorithms useful to optimization problems that fit well with |dwave_short| +quantum computers. + +Like |dwave_short| quantum computers, all other supported samplers must have +``sample_qubo`` and ``sample_ising`` methods for solving :term:`Ising` and +:term:`QUBO` models and return an iterable of samples in order of increasing +energy. You can set a default sampler using the +:func:`~dwave_networkx.default_sampler.set_default_sampler` function. + +Usage Information +================= + +* :ref:`index_concepts` for terminology +* :ref:`qpu_topologies` for an introduction to :term:`QPU` + :term:`topologies ` such as the :term:`Pegasus` graph +* :ref:`concept_models_bqm` for an introduction to binary quadratic models + (:term:`BQM`) +* :ref:`concept_samplers` for an introduction to :term:`samplers ` \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 1559a180..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,6 +0,0 @@ -Installation -================ - -.. include:: README.rst - :start-after: installation-start-marker - :end-before: installation-end-marker diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index 66b7ac9b..00000000 --- a/docs/intro.rst +++ /dev/null @@ -1,41 +0,0 @@ -============ -Introduction -============ - -D-Wave NetworkX provides tools for working with Quantum Processing Unit (QPU) -topology graphs, such as the :term:`Pegasus` used on the Advantage\ |TM| system, -and implementations of graph-theory algorithms on D-Wave quantum computers and -other binary quadratic model :term:`sampler`\ s; for example, functions such as -:func:`.draw_pegasus` provide easy visualization for Pegasus graphs; functions -such as :func:`~dwave_networkx.algorithms.max_cut.maximum_cut` or -:func:`~dwave_networkx.algorithms.cover.min_vertex_cover` provide graph algorithms -useful to optimization problems that fit well with D-Wave quantum computers. - -Like D-Wave quantum computers, all other supported samplers must have -``sample_qubo`` and ``sample_ising`` methods for solving :term:`Ising` and -:term:`QUBO` models and return an iterable of samples in order of increasing -energy. You can set a default sampler using the -:func:`~dwave_networkx.default_sampler.set_default_sampler` function. - -* For an introduction to quantum processing unit (QPU) topologies such as the - Pegasus graph, see :std:doc:`Topology `. -* For an introduction to binary quadratic models (BQMs), see - :std:doc:`Binary Quadratic Models `. -* For an introduction to samplers, see - :std:doc:`Samplers and Composites `. - -Example -======= - -This example creates a Pegasus graph (used by Advantage) and a small Zephyr graph -(used by the Advantage2\ |TM| prototype made available in Leap\ |TM| in June 2022): - -.. |TM| replace:: :sup:`TM` - ->>> import dwave_networkx as dnx -... ->>> # Advantage ->>> P16 = dnx.pegasus_graph(16) -... ->>> # Advantage2 ->>> Z4 = dnx.zephyr_graph(4) diff --git a/docs/license.rst b/docs/license.rst deleted file mode 100644 index e3482d28..00000000 --- a/docs/license.rst +++ /dev/null @@ -1,4 +0,0 @@ -License -========= - -.. include:: LICENSE.txt diff --git a/docs/reference/algorithms/canonicalization.rst b/docs/reference/algorithms/canonicalization.rst deleted file mode 100644 index cb4d2815..00000000 --- a/docs/reference/algorithms/canonicalization.rst +++ /dev/null @@ -1,12 +0,0 @@ -**************** -Canonicalization -**************** - -.. automodule:: dwave_networkx.algorithms.canonicalization - -.. currentmodule:: dwave_networkx - -.. autosummary:: - :toctree: generated/ - - canonical_chimera_labeling diff --git a/docs/reference/algorithms/clique.rst b/docs/reference/algorithms/clique.rst deleted file mode 100644 index 54a357f7..00000000 --- a/docs/reference/algorithms/clique.rst +++ /dev/null @@ -1,23 +0,0 @@ -*************** -Clique -*************** - -A clique in an undirected graph G = (V, E) is a subset of the vertex set -such that for every two vertices in C there exists an edge connecting the two. - -.. figure:: ../../_images/clique.png - :name: Cover - :alt: image - :align: center - :scale: 40 % - -.. automodule:: dwave_networkx.algorithms.clique - -.. currentmodule:: dwave_networkx - -.. autosummary:: - :toctree: generated/ - - maximum_clique - clique_number - is_clique diff --git a/docs/reference/algorithms/coloring.rst b/docs/reference/algorithms/coloring.rst deleted file mode 100644 index bc329fa3..00000000 --- a/docs/reference/algorithms/coloring.rst +++ /dev/null @@ -1,31 +0,0 @@ -******** -Coloring -******** - -Graph coloring is the problem of assigning a color to the vertices of a graph -in a way that no adjacent vertices have the same color. - -Example -------- - -The map-coloring problem is to assign a color to each region of a map -(represented by a vertex on a graph) such that any two regions sharing a -border (represented by an edge of the graph) have different colors. - -.. figure:: ../../_images/Problem_MapColoring.png - :name: Problem_MapColoringColoring - :alt: image - :align: center - :scale: 70 % - - Coloring a map of Canada with four colors. - -.. automodule:: dwave_networkx.algorithms.coloring -.. autosummary:: - :toctree: generated/ - - is_vertex_coloring - min_vertex_color - min_vertex_color_qubo - vertex_color - vertex_color_qubo diff --git a/docs/reference/algorithms/cover.rst b/docs/reference/algorithms/cover.rst deleted file mode 100644 index 78ad9109..00000000 --- a/docs/reference/algorithms/cover.rst +++ /dev/null @@ -1,25 +0,0 @@ -***** -Cover -***** - -Vertex covering is the problem of finding a set of vertices such that all -the edges of the graph are incident to at least one of the vertices in the -set. - -.. figure:: ../../_images/Cover.png - :name: CoverCover - :alt: image - :align: center - :scale: 40 % - - Cover for a Chimera unit cell: the nodes of both the blue set of vertices - (the horizontal tile of the Chimera unit cell) and the red set - (vertical tile) connect to all 16 edges of the graph. - -.. automodule:: dwave_networkx.algorithms.cover -.. autosummary:: - :toctree: generated/ - - min_weighted_vertex_cover - min_vertex_cover - is_vertex_cover diff --git a/docs/reference/algorithms/elimination_ordering.rst b/docs/reference/algorithms/elimination_ordering.rst deleted file mode 100644 index 897bc844..00000000 --- a/docs/reference/algorithms/elimination_ordering.rst +++ /dev/null @@ -1,31 +0,0 @@ -******************** -Elimination Ordering -******************** - -Many algorithms for NP-hard problems are exponential in treewidth. However, -finding a lower bound on treewidth is in itself NP-complete. [Gog2004]_ -describes a branch-and-bound algorithm for computing the treewidth of an -undirected graph by searching in the space of *perfect elimination ordering* of -vertices of the graph. - -A *clique* of a graph is a fully-connected subset of vertices; that is, every -pair of vertices in the clique share an edge. A *simplicial* vertex is one -whose neighborhood induces a clique. A perfect elimination ordering is an -ordering of vertices :math:`1..n` such that any vertex :math:`i` is simplicial -for the subset of vertices :math:`i..n`. - -.. automodule:: dwave_networkx.algorithms.elimination_ordering -.. autosummary:: - :toctree: generated/ - - chimera_elimination_order - elimination_order_width - is_almost_simplicial - is_simplicial - max_cardinality_heuristic - minor_min_width - min_fill_heuristic - min_width_heuristic - pegasus_elimination_order - treewidth_branch_and_bound - diff --git a/docs/reference/algorithms/index.rst b/docs/reference/algorithms/index.rst deleted file mode 100644 index 88df60e9..00000000 --- a/docs/reference/algorithms/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _algorithms_dnx: - -********** -Algorithms -********** - -Implementations of graph-theory algorithms on the D-Wave system and other -binary quadratic model samplers. - -.. currentmodule:: dwave_networkx - -.. toctree:: - :maxdepth: 2 - - canonicalization - clique - coloring - cover - elimination_ordering - markov - matching - max_cut - packing - partition - social - tsp diff --git a/docs/reference/algorithms/markov.rst b/docs/reference/algorithms/markov.rst deleted file mode 100644 index 8831e709..00000000 --- a/docs/reference/algorithms/markov.rst +++ /dev/null @@ -1,10 +0,0 @@ -*************** -Markov Networks -*************** - -.. automodule:: dwave_networkx.algorithms.markov -.. autosummary:: - :toctree: generated/ - - sample_markov_network - markov_network_bqm diff --git a/docs/reference/algorithms/matching.rst b/docs/reference/algorithms/matching.rst deleted file mode 100644 index a57b8483..00000000 --- a/docs/reference/algorithms/matching.rst +++ /dev/null @@ -1,23 +0,0 @@ -******** -Matching -******** - -A matching is a subset of graph edges in which no vertex occurs more than once. - -.. figure:: ../../_images/Match.png - :name: Matching - :alt: image - :align: center - :scale: 40 % - - A matching for a Chimera unit cell: no vertex is incident to more than one - edge in the set of blue edges - -.. automodule:: dwave_networkx.algorithms.matching -.. autosummary:: - :toctree: generated/ - - matching_bqm - maximal_matching_bqm - min_maximal_matching_bqm - min_maximal_matching diff --git a/docs/reference/algorithms/max_cut.rst b/docs/reference/algorithms/max_cut.rst deleted file mode 100644 index 50644a59..00000000 --- a/docs/reference/algorithms/max_cut.rst +++ /dev/null @@ -1,23 +0,0 @@ -*********** -Maximum Cut -*********** - -A maximum cut is a subset of a graph's vertices such that the number of edges -between this subset and the remaining vertices is as large as possible. - -.. figure:: ../../_images/MaxCut.png - :name: Cut - :alt: image - :align: center - :scale: 60 % - - Maximum cut for a Chimera unit cell: the blue line around the subset of nodes - {4, 5, 6, 7} cuts 16 edges; adding or removing a node decreases - the number of edges between the two complementary subsets of the graph. - -.. automodule:: dwave_networkx.algorithms.max_cut -.. autosummary:: - :toctree: generated/ - - maximum_cut - weighted_maximum_cut diff --git a/docs/reference/algorithms/packing.rst b/docs/reference/algorithms/packing.rst deleted file mode 100644 index c186e3a3..00000000 --- a/docs/reference/algorithms/packing.rst +++ /dev/null @@ -1,39 +0,0 @@ -*************** -Independent Set -*************** - -An independent set is a set of a graph's vertices with no edge connecting any -of its member pairs. - -.. figure:: ../../_images/Cover.png - :name: CoverIndependentSet - :alt: image - :align: center - :scale: 40 % - - Independent sets for a Chimera unit cell: the nodes of both the blue set - of vertices (the horizontal tile of the Chimera unit cell) and the red set - (vertical tile) are independent sets of the graph, with no blue node adjacent - to another blue node and likewise for red nodes. - -.. automodule:: dwave_networkx.algorithms.independent_set - -.. currentmodule:: dwave_networkx - -.. autosummary:: - :toctree: generated/ - - maximum_weighted_independent_set - maximum_independent_set - is_independent_set - -Helper Functions ----------------- - -.. currentmodule:: dwave_networkx.algorithms.independent_set - -.. autosummary:: - :toctree: generated/ - - maximum_weighted_independent_set_qubo - diff --git a/docs/reference/algorithms/partition.rst b/docs/reference/algorithms/partition.rst deleted file mode 100644 index d1bbc5d1..00000000 --- a/docs/reference/algorithms/partition.rst +++ /dev/null @@ -1,23 +0,0 @@ -************* -Partitioning -************* - -A `k`-partition consists of `k` disjoint and equally sized subsets of a -graph's vertices such that the total number of edges between nodes in -distinct subsets is as small as possible. - -.. figure:: ../../_images/Partitioning.png - :name: Partition - :alt: image - :align: center - :scale: 60 % - - A 2-partition for a simple graph: the nodes in blue are in the - '0' subset, and the nodes in red are in the '1' subset. There are no - other arrangements with fewer edges between two equally sized subsets. - -.. automodule:: dwave_networkx.algorithms.partition -.. autosummary:: - :toctree: generated/ - - partition \ No newline at end of file diff --git a/docs/reference/algorithms/social.rst b/docs/reference/algorithms/social.rst deleted file mode 100644 index 89ba0318..00000000 --- a/docs/reference/algorithms/social.rst +++ /dev/null @@ -1,24 +0,0 @@ -****** -Social -****** - -A signed social network graph is a graph whose signed edges represent -friendly/hostile interactions between vertices. - -.. figure:: ../../_images/Social.png - :name: Social - :alt: image - :align: center - :scale: 80 % - - A signed social graph for three nodes, where Eve and Bob are friendly with - each other and hostile to Alice. This network is balanced because it can - be cleanly divided into two subsets, {Bob, Eve} and {Alice}, with friendly - relations within each subset and only hostile relations between the subsets. - -.. automodule:: dwave_networkx.algorithms.social -.. autosummary:: - :toctree: generated/ - - structural_imbalance - structural_imbalance_ising diff --git a/docs/reference/algorithms/tsp.rst b/docs/reference/algorithms/tsp.rst deleted file mode 100644 index 72c73576..00000000 --- a/docs/reference/algorithms/tsp.rst +++ /dev/null @@ -1,21 +0,0 @@ -********************* -Traveling Salesperson -********************* - -A traveling salesperson route is an ordering of the vertices in a complete weighted -graph. - -.. figure:: ../../_images/tsp.png - :name: TSP_route - :alt: image - :align: center - :scale: 80 % - - A traveling salesperson route of [2, 1, 0, 3]. - -.. automodule:: dwave_networkx.algorithms.tsp -.. autosummary:: - :toctree: generated/ - - traveling_salesperson - traveling_salesperson_qubo diff --git a/docs/reference/default_sampler.rst b/docs/reference/default_sampler.rst deleted file mode 100644 index e5868d52..00000000 --- a/docs/reference/default_sampler.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _default_sampler_dnx: - -Default sampler -*************** - -.. currentmodule:: dwave_networkx.default_sampler - -.. automodule:: dwave_networkx.default_sampler - -Functions ---------- -.. autosummary:: - :toctree: generated/ - - set_default_sampler - unset_default_sampler - get_default_sampler diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index e043452b..00000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _reference_dnx: - -Reference Documentation -************************* - - :Release: |release| - :Date: |today| - -.. toctree:: - :maxdepth: 2 - - algorithms/index - drawing - generators - utilities - default_sampler diff --git a/docs/reference/utilities/index.rst b/docs/reference/utilities/index.rst deleted file mode 100644 index abcf4bfb..00000000 --- a/docs/reference/utilities/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _index_conversion_classes: - -Coordinates Conversion -********************** - -.. automodule:: dwave_networkx - -.. autoclass:: chimera_coordinates - -.. autoclass:: pegasus_coordinates - -.. autoclass:: zephyr_coordinates diff --git a/docs/requirements.txt b/docs/requirements.txt index efa74079..a1cfbb3d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,2 @@ -sphinx -sphinx_rtd_theme -recommonmark +pydata-sphinx-theme==0.14.3 +sphinx==7.3.7 \ No newline at end of file diff --git a/docs/sdk_index.rst b/docs/sdk_index.rst deleted file mode 100644 index 06c58c28..00000000 --- a/docs/sdk_index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _sdk_index_dnx: - -============== -dwave-networkx -============== - -.. include:: README.rst - :start-after: index-start-marker - :end-before: index-end-marker - -.. include:: index.rst - :start-after: sdk-start-marker - :end-before: sdk-end-marker - -.. toctree:: - :caption: Code - :maxdepth: 1 - - Source diff --git a/docs/reference/utilities.rst b/docs/utilities.rst similarity index 71% rename from docs/reference/utilities.rst rename to docs/utilities.rst index d9be5841..78f2f018 100644 --- a/docs/reference/utilities.rst +++ b/docs/utilities.rst @@ -1,12 +1,15 @@ -********* +.. _dnx_utilities: + +========= Utilities -********* +========= .. automodule:: dwave_networkx.utils .. currentmodule:: dwave_networkx.utils Decorators ----------- +========== + .. automodule:: dwave_networkx.utils.decorators .. autosummary:: :toctree: generated/ @@ -15,21 +18,15 @@ Decorators .. currentmodule:: dwave_networkx -.. toctree:: - :hidden: - - utilities/index - Graph Indexing --------------- +============== -See :ref:`index_conversion_classes` on instantiating the needed lattice size -and setting correct domain and range for coordinates in a QPU working graph. - -For the iterator versions of these functions, see the code. +See the :ref:`dnx_coordinates_conversion` subsection on instantiating the needed +lattice size and setting correct domain and range for coordinates in a QPU +working graph. For the iterator versions of these functions, see the code. Chimera -~~~~~~~ +------- .. autosummary:: :toctree: generated/ @@ -40,9 +37,9 @@ Chimera chimera_coordinates.linear_to_chimera chimera_sublattice_mappings find_chimera_indices - + Pegasus -~~~~~~~ +------- .. autosummary:: :toctree: generated/ @@ -60,7 +57,7 @@ Pegasus Zephyr -~~~~~~ +------ .. autosummary:: :toctree: generated/ @@ -72,8 +69,24 @@ Zephyr zephyr_sublattice_mappings +.. _dnx_coordinates_conversion: + +Coordinates Conversion +---------------------- + +.. automodule:: dwave_networkx + +.. autoclass:: chimera_coordinates + +.. autoclass:: pegasus_coordinates + +.. autoclass:: zephyr_coordinates + + + Exceptions ----------- +========== + .. automodule:: dwave_networkx.exceptions .. autosummary:: :toctree: generated/ diff --git a/dwave_networkx/generators/chimera.py b/dwave_networkx/generators/chimera.py index 02f15b03..f31ee105 100644 --- a/dwave_networkx/generators/chimera.py +++ b/dwave_networkx/generators/chimera.py @@ -706,8 +706,7 @@ def chimera_sublattice_mappings(source, target, offset_list=None): .. [#] The yield is the percentage of working qubits on a QPU and the subset - of available qubits is called - the `working graph `_. + of available qubits is called the :ref:`working graph `. Parameters ---------- diff --git a/dwave_networkx/generators/pegasus.py b/dwave_networkx/generators/pegasus.py index b016a9b0..8bec9131 100644 --- a/dwave_networkx/generators/pegasus.py +++ b/dwave_networkx/generators/pegasus.py @@ -1121,8 +1121,7 @@ def pegasus_sublattice_mappings(source, target, offset_list=None): .. [#] The yield is the percentage of working qubits on a QPU and the subset - of available qubits is called - the `working graph `_. + of available qubits is called the :ref:`working graph `. Parameters ---------- diff --git a/dwave_networkx/generators/zephyr.py b/dwave_networkx/generators/zephyr.py index 001e3400..e71f5993 100644 --- a/dwave_networkx/generators/zephyr.py +++ b/dwave_networkx/generators/zephyr.py @@ -611,8 +611,7 @@ def zephyr_sublattice_mappings(source, target, offset_list=None): .. [#] The yield is the percentage of working qubits on a QPU and the subset - of available qubits is called - the `working graph `_. + of available qubits is called the :ref:`working graph `. Parameters ----------