From bb130736d18ea0dc8df1ad0de7cba8a4be2b5215 Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Tue, 25 Feb 2025 10:00:27 -0800
Subject: [PATCH 1/7] Restructure docs
---
.gitignore | 1 +
README.rst | 34 +-
docs/bibliography.rst | 37 --
docs/conf.py | 157 +--------
docs/index.rst | 102 +++---
docs/installation.rst | 6 -
docs/intro.rst | 41 ---
docs/license.rst | 4 -
docs/reference/algorithms.rst | 317 ++++++++++++++++++
.../reference/algorithms/canonicalization.rst | 12 -
docs/reference/algorithms/clique.rst | 23 --
docs/reference/algorithms/coloring.rst | 31 --
docs/reference/algorithms/cover.rst | 25 --
.../algorithms/elimination_ordering.rst | 31 --
docs/reference/algorithms/index.rst | 26 --
docs/reference/algorithms/markov.rst | 10 -
docs/reference/algorithms/matching.rst | 23 --
docs/reference/algorithms/max_cut.rst | 23 --
docs/reference/algorithms/packing.rst | 39 ---
docs/reference/algorithms/partition.rst | 23 --
docs/reference/algorithms/social.rst | 24 --
docs/reference/algorithms/tsp.rst | 21 --
docs/reference/api_ref.rst | 14 +
docs/reference/default_sampler.rst | 16 +-
docs/reference/drawing.rst | 21 +-
docs/reference/generators.rst | 17 +-
docs/reference/index.rst | 16 -
docs/reference/utilities.rst | 49 ++-
docs/reference/utilities/index.rst | 12 -
docs/requirements.txt | 6 +-
docs/sdk_index.rst | 19 --
31 files changed, 466 insertions(+), 714 deletions(-)
delete mode 100644 docs/bibliography.rst
delete mode 100644 docs/installation.rst
delete mode 100644 docs/intro.rst
delete mode 100644 docs/license.rst
create mode 100644 docs/reference/algorithms.rst
delete mode 100644 docs/reference/algorithms/canonicalization.rst
delete mode 100644 docs/reference/algorithms/clique.rst
delete mode 100644 docs/reference/algorithms/coloring.rst
delete mode 100644 docs/reference/algorithms/cover.rst
delete mode 100644 docs/reference/algorithms/elimination_ordering.rst
delete mode 100644 docs/reference/algorithms/index.rst
delete mode 100644 docs/reference/algorithms/markov.rst
delete mode 100644 docs/reference/algorithms/matching.rst
delete mode 100644 docs/reference/algorithms/max_cut.rst
delete mode 100644 docs/reference/algorithms/packing.rst
delete mode 100644 docs/reference/algorithms/partition.rst
delete mode 100644 docs/reference/algorithms/social.rst
delete mode 100644 docs/reference/algorithms/tsp.rst
create mode 100644 docs/reference/api_ref.rst
delete mode 100644 docs/reference/index.rst
delete mode 100644 docs/reference/utilities/index.rst
delete mode 100644 docs/sdk_index.rst
diff --git a/.gitignore b/.gitignore
index 98669460..a8845389 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
build
+_build
dist
dwave_networkx.egg-info
*.pyc
diff --git a/README.rst b/README.rst
index 930e2869..e7af53a4 100644
--- a/README.rst
+++ b/README.rst
@@ -7,19 +7,21 @@
.. 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
+.. |tm| replace:: :sup:`TM`
-D-Wave NetworkX is an extension of `NetworkX <https://networkx.org>`_\ ---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.
+.. start_dnx_about
-.. |TM| replace:: :sup:`TM`
+dwave-networkx is an extension of `NetworkX <https://networkx.org>`_\ ---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| 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.
@@ -28,27 +30,23 @@ This example generates a Pegasus graph of the size used by Advantage QPUs.
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
=======
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..ae4f6819 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',
@@ -38,19 +22,14 @@
'sphinx.ext.napoleon',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
+ 'sphinx_design',
'sphinx.ext.ifconfig',
]
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 +37,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 +53,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 +65,17 @@
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.
+# TODO: replace oceandocs & sysdocs_gettingstarted
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)}
diff --git a/docs/index.rst b/docs/index.rst
index ac7fc315..97ba68a7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,68 +1,54 @@
-.. -*- 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 <https://github.com/dwavesystems/dwave-networkx>`_.
- Documentation for the version currently installed by
- `dwave-ocean-sdk <https://github.com/dwavesystems/dwave-ocean-sdk>`_
- is here: :std:doc:`dwave-networkx <oceandocs:docs_dnx/sdk_index>`.
-
-.. sdk-start-marker
-
-.. toctree::
- :maxdepth: 1
-
- intro
- reference/index
- bibliography
-
-.. sdk-end-marker
+.. dropdown:: About dwave-networkx
+
+ .. include:: README.rst
+ :start-after: start_dnx_about
+ :end-before: end_dnx_about
+
+ 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 <oceandocs:concepts/topology>`.
+ * For an introduction to binary quadratic models (BQMs), see
+ :std:doc:`Binary Quadratic Models <oceandocs:concepts/bqm>`.
+ * For an introduction to samplers, see
+ :std:doc:`Samplers and Composites <oceandocs:concepts/samplers>`.
+
+ 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)
+
+Reference Documentation
+=======================
.. toctree::
- :caption: Code
:maxdepth: 1
- Source <https://github.com/dwavesystems/dwave-networkx>
- installation
- license
-
-.. toctree::
- :caption: D-Wave's Ocean Software
- :maxdepth: 1
-
- Ocean Home <https://ocean.dwavesys.com/>
- Ocean Documentation <https://docs.ocean.dwavesys.com>
- Ocean Glossary <https://docs.ocean.dwavesys.com/en/stable/concepts/index.html>
-
-.. toctree::
- :caption: D-Wave
- :maxdepth: 1
-
- D-Wave <https://www.dwavesys.com>
- Leap <https://cloud.dwavesys.com/leap/>
- D-Wave System Documentation <https://docs.dwavesys.com/docs/latest/index.html>
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-* `Glossary <https://docs.ocean.dwavesys.com/en/stable/concepts/index.html>`_
\ No newline at end of file
+ reference/api_ref
\ 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 <oceandocs:concepts/topology>`.
-* For an introduction to binary quadratic models (BQMs), see
- :std:doc:`Binary Quadratic Models <oceandocs:concepts/bqm>`.
-* For an introduction to samplers, see
- :std:doc:`Samplers and Composites <oceandocs:concepts/samplers>`.
-
-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.rst b/docs/reference/algorithms.rst
new file mode 100644
index 00000000..1922efbb
--- /dev/null
+++ b/docs/reference/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/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/api_ref.rst b/docs/reference/api_ref.rst
new file mode 100644
index 00000000..9c2f59a7
--- /dev/null
+++ b/docs/reference/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/reference/default_sampler.rst b/docs/reference/default_sampler.rst
index e5868d52..9540c0d2 100644
--- a/docs/reference/default_sampler.rst
+++ b/docs/reference/default_sampler.rst
@@ -1,17 +1,19 @@
-.. _default_sampler_dnx:
+.. _dnx_default_sampler:
+===============
Default sampler
-***************
+===============
.. currentmodule:: dwave_networkx.default_sampler
.. automodule:: dwave_networkx.default_sampler
Functions
----------
+=========
+
.. autosummary::
- :toctree: generated/
+ :toctree: generated/
- set_default_sampler
- unset_default_sampler
- get_default_sampler
+ set_default_sampler
+ unset_default_sampler
+ get_default_sampler
diff --git a/docs/reference/drawing.rst b/docs/reference/drawing.rst
index 5445a724..0cdb78ec 100644
--- a/docs/reference/drawing.rst
+++ b/docs/reference/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
@@ -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.
@@ -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.
diff --git a/docs/reference/generators.rst b/docs/reference/generators.rst
index 9be9df2b..ef83c502 100644
--- a/docs/reference/generators.rst
+++ b/docs/reference/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
@@ -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/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.rst b/docs/reference/utilities.rst
index d9be5841..78f2f018 100644
--- a/docs/reference/utilities.rst
+++ b/docs/reference/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/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..90727eda 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,3 @@
-sphinx
-sphinx_rtd_theme
-recommonmark
+pydata-sphinx-theme==0.14.3
+sphinx==7.3.7
+sphinx-design==0.5.0
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 <https://github.com/dwavesystems/dwave-networkx>
From bac8e8aa3c21dac2564afc458083ad59d4cb85b5 Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Tue, 25 Feb 2025 10:39:38 -0800
Subject: [PATCH 2/7] Update xrefs and refs to doc-site URLs
---
README.rst | 4 +--
docs/conf.py | 6 ++++
docs/index.rst | 49 ++++++++++------------------
dwave_networkx/generators/chimera.py | 3 +-
dwave_networkx/generators/pegasus.py | 3 +-
dwave_networkx/generators/zephyr.py | 3 +-
6 files changed, 28 insertions(+), 40 deletions(-)
diff --git a/README.rst b/README.rst
index e7af53a4..a6755b6d 100644
--- a/README.rst
+++ b/README.rst
@@ -28,8 +28,6 @@ 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.
-
.. end_dnx_about
Installation
@@ -56,5 +54,7 @@ Released under the Apache License 2.0.
Contributing
============
+.. todo:: update this link
+
Ocean's `contributing guide <https://docs.ocean.dwavesys.com/en/stable/contributing.html>`_
has guidelines for contributing to Ocean packages.
diff --git a/docs/conf.py b/docs/conf.py
index ae4f6819..24d9484f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -79,3 +79,9 @@
'networkx': ('https://networkx.github.io/documentation/stable/', None),
'oceandocs': ('https://docs.ocean.dwavesys.com/en/latest/', None),
'sysdocs_gettingstarted': ('https://docs.dwavesys.com/docs/latest/', None)}
+
+# global substitutions
+rst_epilog = """
+.. |dwave_short| unicode:: D-Wave
+.. |tm| unicode:: U+2122
+"""
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 97ba68a7..086eb72b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,40 +10,25 @@ dwave-networkx
:start-after: start_dnx_about
:end-before: end_dnx_about
- 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
+ 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.
- * For an introduction to quantum processing unit (QPU) topologies such as the
- Pegasus graph, see :std:doc:`Topology <oceandocs:concepts/topology>`.
- * For an introduction to binary quadratic models (BQMs), see
- :std:doc:`Binary Quadratic Models <oceandocs:concepts/bqm>`.
- * For an introduction to samplers, see
- :std:doc:`Samplers and Composites <oceandocs:concepts/samplers>`.
-
- 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)
+ * For an introduction to :term:`QPU` :term:`topologies <topology>` such as
+ the Pegasus graph, see the :ref:`qpu_topologies` section.
+ * For an introduction to binary quadratic models (:term:`BQM`), see the
+ :ref:`concept_models_bqm`.
+ * For an introduction to samplers, see the :ref:`concept_samplers`
+ section.
Reference Documentation
=======================
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 <https://docs.dwavesys.com/docs/latest/c_gs_4.html#the-working-graph>`_.
+ of available qubits is called the :ref:`working graph <qpu_topologies>`.
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 <https://docs.dwavesys.com/docs/latest/c_gs_4.html#the-working-graph>`_.
+ of available qubits is called the :ref:`working graph <qpu_topologies>`.
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 <https://docs.dwavesys.com/docs/latest/c_gs_4.html#the-working-graph>`_.
+ of available qubits is called the :ref:`working graph <qpu_topologies>`.
Parameters
----------
From a112625023a82b05c0c800084424c0aa3928a127 Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Thu, 27 Feb 2025 10:04:05 -0800
Subject: [PATCH 3/7] Switch api and about, flatten licenses (in sdk), add todo
---
docs/LICENSE.txt | 1 -
docs/index.rst | 59 ++++++++++++++++++++++---------------------
docs/requirements.txt | 3 +--
3 files changed, 31 insertions(+), 32 deletions(-)
delete mode 120000 docs/LICENSE.txt
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/index.rst b/docs/index.rst
index 086eb72b..82f38203 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,36 +4,37 @@
dwave-networkx
==============
-.. dropdown:: About dwave-networkx
-
- .. 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.
-
- * For an introduction to :term:`QPU` :term:`topologies <topology>` such as
- the Pegasus graph, see the :ref:`qpu_topologies` section.
- * For an introduction to binary quadratic models (:term:`BQM`), see the
- :ref:`concept_models_bqm`.
- * For an introduction to samplers, see the :ref:`concept_samplers`
- section.
-
-Reference Documentation
-=======================
.. toctree::
+ :caption: Reference documentation for dwave-networkx:
:maxdepth: 1
- reference/api_ref
\ No newline at end of file
+ reference/api_ref
+
+
+About dwave-networkx
+====================
+
+.. 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.
+
+* For an introduction to :term:`QPU` :term:`topologies <topology>` such as
+ the Pegasus graph, see the :ref:`qpu_topologies` section.
+* For an introduction to binary quadratic models (:term:`BQM`), see the
+ :ref:`concept_models_bqm`.
+* For an introduction to samplers, see the :ref:`concept_samplers`
+ section.
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 90727eda..a1cfbb3d 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,2 @@
pydata-sphinx-theme==0.14.3
-sphinx==7.3.7
-sphinx-design==0.5.0
+sphinx==7.3.7
\ No newline at end of file
From 986287405e0d650385468670c621940f183d7e8c Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Fri, 28 Feb 2025 11:41:59 -0800
Subject: [PATCH 4/7] Minor updates for uniformity
---
docs/conf.py | 6 +++---
docs/index.rst | 17 +++++++++++------
2 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index 24d9484f..2fb2d4db 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -74,11 +74,11 @@
}
html_sidebars = {"**": ["search-field", "sidebar-nav-bs"]} # remove ads
-# TODO: replace oceandocs & sysdocs_gettingstarted
+# TODO: verify the link to dwave docs
intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
'networkx': ('https://networkx.github.io/documentation/stable/', 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 = """
diff --git a/docs/index.rst b/docs/index.rst
index 82f38203..a3a57b53 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,9 +32,14 @@ Like |dwave_short| quantum computers, all other supported samplers must have
energy. You can set a default sampler using the
:func:`~dwave_networkx.default_sampler.set_default_sampler` function.
-* For an introduction to :term:`QPU` :term:`topologies <topology>` such as
- the Pegasus graph, see the :ref:`qpu_topologies` section.
-* For an introduction to binary quadratic models (:term:`BQM`), see the
- :ref:`concept_models_bqm`.
-* For an introduction to samplers, see the :ref:`concept_samplers`
- section.
\ No newline at end of file
+Usage Information
+=================
+
+.. todo:: add the intersphinx prefix to enable these links for self builds
+
+* :ref:`index_concepts` for terminology
+* :ref:`qpu_topologies` for an introduction to :term:`QPU`
+ :term:`topologies <topology>` 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 <sampler>`
\ No newline at end of file
From 8d945049a83a4ea8174d13cd2a3f0a802bb3f56e Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Mon, 3 Mar 2025 11:58:24 -0800
Subject: [PATCH 5/7] Flatten ref folder
---
.gitignore | 6 +++---
docs/{reference => }/algorithms.rst | 18 +++++++++---------
docs/{reference => }/api_ref.rst | 0
docs/{reference => }/default_sampler.rst | 0
docs/{reference => }/drawing.rst | 6 +++---
docs/{reference => }/generators.rst | 2 +-
docs/index.rst | 2 +-
docs/{reference => }/utilities.rst | 0
8 files changed, 17 insertions(+), 17 deletions(-)
rename docs/{reference => }/algorithms.rst (95%)
rename docs/{reference => }/api_ref.rst (100%)
rename docs/{reference => }/default_sampler.rst (100%)
rename docs/{reference => }/drawing.rst (96%)
rename docs/{reference => }/generators.rst (96%)
rename docs/{reference => }/utilities.rst (100%)
diff --git a/.gitignore b/.gitignore
index a8845389..519d747d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,9 +6,9 @@ dwave_networkx.egg-info
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/docs/reference/algorithms.rst b/docs/algorithms.rst
similarity index 95%
rename from docs/reference/algorithms.rst
rename to docs/algorithms.rst
index 1922efbb..fdeebbe9 100644
--- a/docs/reference/algorithms.rst
+++ b/docs/algorithms.rst
@@ -29,7 +29,7 @@ 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
+.. figure:: _images/clique.png
:name: Cover
:alt: image
:align: center
@@ -59,7 +59,7 @@ 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
+.. figure:: _images/Problem_MapColoring.png
:name: Problem_MapColoringColoring
:alt: image
:align: center
@@ -86,7 +86,7 @@ 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
+.. figure:: _images/Cover.png
:name: CoverCover
:alt: image
:align: center
@@ -158,7 +158,7 @@ Matching
A matching is a subset of graph edges in which no vertex occurs more than once.
-.. figure:: ../_images/Match.png
+.. figure:: _images/Match.png
:name: Matching
:alt: image
:align: center
@@ -185,7 +185,7 @@ 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
+.. figure:: _images/MaxCut.png
:name: Cut
:alt: image
:align: center
@@ -211,7 +211,7 @@ 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
+.. figure:: _images/Cover.png
:name: CoverIndependentSet
:alt: image
:align: center
@@ -248,7 +248,7 @@ 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
+.. figure:: _images/Partitioning.png
:name: Partition
:alt: image
:align: center
@@ -273,7 +273,7 @@ Social
A signed social network graph is a graph whose signed edges represent
friendly/hostile interactions between vertices.
-.. figure:: ../_images/Social.png
+.. figure:: _images/Social.png
:name: Social
:alt: image
:align: center
@@ -300,7 +300,7 @@ Traveling Salesperson
A traveling salesperson route is an ordering of the vertices in a complete
weighted graph.
-.. figure:: ../_images/tsp.png
+.. figure:: _images/tsp.png
:name: TSP_route
:alt: image
:align: center
diff --git a/docs/reference/api_ref.rst b/docs/api_ref.rst
similarity index 100%
rename from docs/reference/api_ref.rst
rename to docs/api_ref.rst
diff --git a/docs/reference/default_sampler.rst b/docs/default_sampler.rst
similarity index 100%
rename from docs/reference/default_sampler.rst
rename to docs/default_sampler.rst
diff --git a/docs/reference/drawing.rst b/docs/drawing.rst
similarity index 96%
rename from docs/reference/drawing.rst
rename to docs/drawing.rst
index 0cdb78ec..74b00105 100644
--- a/docs/reference/drawing.rst
+++ b/docs/drawing.rst
@@ -54,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 %
@@ -98,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 %
@@ -139,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 96%
rename from docs/reference/generators.rst
rename to docs/generators.rst
index ef83c502..f70fe3bd 100644
--- a/docs/reference/generators.rst
+++ b/docs/generators.rst
@@ -41,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 %
diff --git a/docs/index.rst b/docs/index.rst
index a3a57b53..a5734a7b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,7 +9,7 @@ dwave-networkx
:caption: Reference documentation for dwave-networkx:
:maxdepth: 1
- reference/api_ref
+ api_ref
About dwave-networkx
diff --git a/docs/reference/utilities.rst b/docs/utilities.rst
similarity index 100%
rename from docs/reference/utilities.rst
rename to docs/utilities.rst
From 01d9b69ae5e92c86b679f115d614397832c0012b Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Tue, 4 Mar 2025 10:22:47 -0800
Subject: [PATCH 6/7] Fix SDK build warning for repo (minimal until last
rebase)
---
README.rst | 4 +---
docs/conf.py | 1 -
2 files changed, 1 insertion(+), 4 deletions(-)
diff --git a/README.rst b/README.rst
index a6755b6d..5272f4a7 100644
--- a/README.rst
+++ b/README.rst
@@ -11,15 +11,13 @@
dwave-networkx
==============
-.. |tm| replace:: :sup:`TM`
-
.. start_dnx_about
dwave-networkx is an extension of `NetworkX <https://networkx.org>`_\ ---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| quantum computer, and implementations of
+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.
diff --git a/docs/conf.py b/docs/conf.py
index 2fb2d4db..379d21a4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -83,5 +83,4 @@
# global substitutions
rst_epilog = """
.. |dwave_short| unicode:: D-Wave
-.. |tm| unicode:: U+2122
"""
\ No newline at end of file
From 7ffa91a19db82630a8ab8bd8314d8bd1b17be49a Mon Sep 17 00:00:00 2001
From: Joel Pasvolsky <jpasvolsky@dwavesys.com>
Date: Tue, 18 Mar 2025 09:41:09 -0700
Subject: [PATCH 7/7] Update xrefs
---
README.rst | 4 +---
docs/conf.py | 2 --
docs/index.rst | 2 --
3 files changed, 1 insertion(+), 7 deletions(-)
diff --git a/README.rst b/README.rst
index 5272f4a7..feece838 100644
--- a/README.rst
+++ b/README.rst
@@ -52,7 +52,5 @@ Released under the Apache License 2.0.
Contributing
============
-.. todo:: update this link
-
-Ocean's `contributing guide <https://docs.ocean.dwavesys.com/en/stable/contributing.html>`_
+Ocean's `contributing guide <https://docs.dwavequantum.com/en/latest/ocean/contribute.html>`_
has guidelines for contributing to Ocean packages.
diff --git a/docs/conf.py b/docs/conf.py
index 379d21a4..c3649ce3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -22,7 +22,6 @@
'sphinx.ext.napoleon',
'sphinx.ext.todo',
'sphinx.ext.viewcode',
- 'sphinx_design',
'sphinx.ext.ifconfig',
]
@@ -74,7 +73,6 @@
}
html_sidebars = {"**": ["search-field", "sidebar-nav-bs"]} # remove ads
-# TODO: verify the link to dwave docs
intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
'networkx': ('https://networkx.github.io/documentation/stable/', None),
'dwave': ('https://docs.dwavequantum.com/en/latest/', None),
diff --git a/docs/index.rst b/docs/index.rst
index a5734a7b..9e0fe511 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,8 +35,6 @@ energy. You can set a default sampler using the
Usage Information
=================
-.. todo:: add the intersphinx prefix to enable these links for self builds
-
* :ref:`index_concepts` for terminology
* :ref:`qpu_topologies` for an introduction to :term:`QPU`
:term:`topologies <topology>` such as the :term:`Pegasus` graph