Moved from branch that spawned dwavesystems#585

JoelPasvolsky · JoelPasvolsky · commit 1a053b873eff · 2025-07-25T15:05:46.000-07:00
diff --git a/docs/utilities.rst b/docs/utilities.rst
@@ -4,6 +4,8 @@
 Utilities
 =========
 
+.. todo:: add dwave_sampler.qpu_graph post https://github.com/dwavesystems/dwave-system/pull/585
+
 .. automodule:: dwave.system.utilities
 
 .. currentmodule:: dwave.system
diff --git a/dwave/system/exceptions.py b/dwave/system/exceptions.py
@@ -14,12 +14,12 @@
 
 
 class FailoverCondition(Exception):
-    """QPU or Solver API call failed with an error that might be mitigated by
-    retrying on a different solver.
+    """QPU or :term:`SAPI` call failed with an error that might be mitigated by
+    retrying on a different :term:`solver`.
     """
 
 
 class RetryCondition(FailoverCondition):
-    """QPU or Solver API call failed with an error that might be mitigated by
-    retrying on the same solver.
+    """QPU or :term:`SAPI` call failed with an error that might be mitigated by
+    retrying (on the same :term:`solver`).
     """
diff --git a/dwave/system/samplers/dwave_sampler.py b/dwave/system/samplers/dwave_sampler.py
@@ -14,9 +14,6 @@
 
 """
 A :ref:`dimod <index_dimod>` :term:`sampler` for D-Wave quantum computers.
-
-See :ref:`Ocean Glossary <index_concepts>`
-for explanations of technical terms in descriptions of Ocean tools.
 """
 
 import copy
@@ -41,25 +38,25 @@
 
 
 def qpu_graph(topology_type, topology_shape, nodelist, edgelist):
-    """Converts node and edge lists to a dwave-networkx compatible graph.
+    """Convert node and edge lists to a ``dwave-networkx`` graph.
 
-    Creates a D-Wave Chimera, Pegasus or Zephyr graph compatible with
-    dwave-networkx libraries. 
+    Creates a QPU topology (Chimera, Pegasus or Zephyr) graph compatible with
+    Ocean software's :ref:`index_dnx`.
 
     Args:
         topology_type (string):
-            The type of lattice. Valid strings are `chimera`, `pegasus`
-            and `zephyr`.
+            Type of lattice. Valid strings are `chimera`, `pegasus` and
+            `zephyr`.
         topology_shape(iterable of ints):
-            Specifies dimensions of the lattice.
+            Dimensions of the lattice.
         nodelist (list of ints):
-            List of nodes in the graph. Node labeling is integer,
-            and compatible with the topology_type linear labeling scheme.
+            List of nodes in the graph. Node labeling is integer and compatible
+            with the linear labeling scheme for the specified ``topology_type``.
         edgelist (list of Tuples):
-            List of edges in the graph, each edge consisting of a pair
-            of nodes.
+            List of edges in the graph, with each edge consisting of a pair of
+            nodes.
     """
-    
+
     if topology_type == 'chimera':
         if not (1 <= len(topology_shape) <=3):
             raise ValueError('topology_shape is incompatible with a chimera lattice.')
@@ -86,27 +83,30 @@ def qpu_graph(topology_type, topology_shape, nodelist, edgelist):
 
 
 class DWaveSampler(dimod.Sampler, dimod.Structured):
-    """A class for using D-Wave quantum computers as samplers for binary quadratic models.
-
-    You can configure your :term:`solver` selection and usage by setting parameters,
-    hierarchically, in a configuration file, as environment variables, or
-    explicitly as input arguments. For more information, see the
-    :ref:`D-Wave Cloud Client <index_cloud>` package's
+    r"""Submits binary quadratic models directly to D-Wave quantum computers.
+
+    Linear and quadratic terms of the :term:`binary quadratic model` (BQM) must
+    map directly to qubit and coupler indices of the selected :term:`QPU`.
+    Typically this mapping (:term:`minor-embedding`) is handled by software
+    (e.g., the :class:`.EmbeddingComposite` class) but for small problems can be
+    manual.
+    You can configure your :term:`solver` selection and usage by setting
+    parameters, hierarchically, in a configuration file, as environment
+    variables, or explicitly as input arguments. For more information, see the
     :meth:`~dwave.cloud.client.Client.get_solvers` method. By default, online
-    D-Wave systems are returned ordered by highest number of qubits.
+    QPUs are returned ordered by highest number of qubits.
 
     Args:
         failover (bool, optional, default=False):
-            Signal a failover condition if a sampling error occurs. When ``True``,
-            raises :exc:`~dwave.system.exceptions.FailoverCondition` or
-            :exc:`~dwave.system.exceptions.RetryCondition` on sampleset resolve
-            to signal failover.
-
-            Actual failover, i.e. selection of a new solver, has to be handled
-            by the user. A convenience method :meth:`.trigger_failover` is available
-            for this. Note that hardware graphs vary between QPUs, so triggering
-            failover results in regenerated :attr:`.nodelist`,  :attr:`.edgelist`, 
-            :attr:`.properties` and :attr:`.parameters`.
+            Signal a failover condition if a sampling error occurs. When
+            ``True``, raises :exc:`~dwave.system.exceptions.FailoverCondition`
+            or :exc:`~dwave.system.exceptions.RetryCondition` on sampleset
+            :meth:`~dimod.SampleSet.resolve` to signal failover.
+            Actual failover (i.e., selection of a new solver) has to be handled
+            by the user. A convenience method :meth:`.trigger_failover` is
+            available for this. Note that hardware graphs vary between QPUs, so
+            triggering failover results in regenerated :attr:`.nodelist`,
+            :attr:`.edgelist`, :attr:`.properties` and :attr:`.parameters`.
 
             .. versionchanged:: 1.16.0
 
@@ -124,7 +124,8 @@ class DWaveSampler(dimod.Sampler, dimod.Structured):
                Ignored since 1.16.0. See note for ``failover`` parameter above.
 
         **config:
-            Keyword arguments passed to :meth:`~dwave.cloud.client.Client.from_config`.
+            Keyword arguments passed to
+            :meth:`~dwave.cloud.client.Client.from_config`.
 
     .. versionadded:: 1.29.0
         Support for context manager protocol.
@@ -151,16 +152,15 @@ class DWaveSampler(dimod.Sampler, dimod.Structured):
 
     Examples:
         This example submits a two-variable Ising problem mapped directly to two
-        adjacent qubits on a D-Wave system. ``qubit_a`` is the first qubit in
+        adjacent qubits on a :term:`QPU`. ``qubit_a`` is the first qubit in
         the QPU's indexed list of qubits and ``qubit_b`` is one of the qubits
-        coupled to it. Other required parameters for communication with the system, such
-        as its URL and an authentication token, are implicitly set in a configuration file
-        or as environment variables, as described in the
-        :ref:`ocean_sapi_access_basic` section.
-        Given sufficient reads (here 100), the quantum
-        computer should return the best solution, :math:`{1, -1}` on ``qubit_a`` and
-        ``qubit_b``, respectively, as its first sample (samples are ordered from
-        lowest energy).
+        coupled to it. Other required parameters for communication with the
+        system, such as its URL and an authentication token, are implicitly set
+        in a configuration file or as environment variables, as described in the
+        :ref:`ocean_sapi_access_basic` section. Given sufficient reads (here
+        100), the quantum computer should return the best solution,
+        :math:`{1, -1}` on ``qubit_a`` and ``qubit_b``, respectively, as its
+        first sample (samples are ordered from lowest energy).
 
         >>> from dwave.system import DWaveSampler
         ...
@@ -173,9 +173,10 @@ class DWaveSampler(dimod.Sampler, dimod.Structured):
         ...     print(sampleset.first.sample[qubit_a] == 1 and sampleset.first.sample[qubit_b] == -1)
         True
 
-    See the :ref:`index_concepts` section
-    for explanations of technical terms in descriptions of Ocean tools.
-
+    See also:
+        *   :ref:`Beginner examples <qpu_index_examples_beginner>` of using
+            :class:`.DWaveSampler`.
+        *   :ref:`qpu_basic_config`.
     """
     def __init__(self, failover=False, retry_interval=-1, **config):
         # strongly prefer QPU solvers; requires kwarg-level override
@@ -212,7 +213,8 @@ def _get_solver(self, *, refresh: bool = False, penalty: Optional[Dict[str, int]
         """Get the least penalized solver from the list of solvers filtered and
         ordered according to user config.
 
-        Note: we need to partially replicate :class:`dwave.cloud.Client.get_solver` logic.
+        Note: we need to partially replicate
+        :class:`dwave.cloud.Client.get_solver` logic.
         """
         if penalty is None:
             penalty = {}
@@ -232,31 +234,26 @@ def _get_solver(self, *, refresh: bool = False, penalty: Optional[Dict[str, int]
             raise SolverNotFoundError("Solver with the requested features not available")
 
     warnings_default = WarningAction.IGNORE
-    """Defines the default behavior for :meth:`.sample_ising`'s  and
-    :meth:`sample_qubo`'s `warnings` kwarg.
+    """Defines the default behavior for ``warnings`` keyword arguments of the
+    :meth:`.sample_ising`  and :meth:`sample_qubo` methods.
     """
 
     @property
     def properties(self):
-        """dict: D-Wave solver properties as returned by a SAPI query.
+        """dict: Solver properties as returned by a :term:`SAPI` query.
 
-        Solver properties are dependent on the selected D-Wave solver and subject to change;
-        for example, new released features may add properties. The
+        Solver properties are dependent on the selected solver and subject to
+        change; for example, new features may add properties. The
         :ref:`qpu_index_solver_properties` and :ref:`qpu_solver_parameters`
-        sections describe the parameters and properties supported on the D-Wave system.
+        sections describe the parameters and properties supported on D-Wave
+        quantum computers.
 
         Examples:
 
             >>> from dwave.system import DWaveSampler
-            >>> with DWaveSampler() as sampler:     # doctest: +SKIP
-            ...     sampler.properties
-            {'anneal_offset_ranges': [[-0.2197463755538704, 0.03821687759418928],
-              [-0.2242514597680286, 0.01718456460967399],
-              [-0.20860153999435985, 0.05511969218508182],
-            # Snipped above response for brevity
-
-        See the :ref:`Ocean Glossary <index_concepts>` section
-        for explanations of technical terms in descriptions of Ocean tools.
+            >>> with DWaveSampler() as sampler:
+            ...     print(sampler.properties['category'])
+            qpu
 
         """
         try:
@@ -267,29 +264,25 @@ def properties(self):
 
     @property
     def parameters(self):
-        """dict[str, list]: D-Wave solver parameters in the form of a dict, where keys are
-        keyword parameters accepted by a SAPI query and values are lists of properties in
+        """dict[str, list]: Solver parameters as returned by a :term:`SAPI`
+        query.
+
+        Keys of the returned dict are keyword parameters accepted by a SAPI
+        query and values are lists of properties in
         :attr:`~DWaveSampler.properties` for each key.
 
-        Solver parameters are dependent on the selected D-Wave solver and subject to change;
-        for example, new released features may add parameters. The
+        Solver parameters are dependent on the selected solver and subject to
+        change; for example, new features may add parameters. The
         :ref:`qpu_index_solver_properties` and :ref:`qpu_solver_parameters`
-        sections describe the parameters and properties supported on the D-Wave system.
+        sections describe the parameters and properties supported on D-Wave
+        quantum computers.
 
         Examples:
 
             >>> from dwave.system import DWaveSampler
-            >>> with DWaveSampler() as sampler:     # doctest: +SKIP
-            ...     sampler.parameters
-            {'anneal_offsets': ['parameters'],
-             'anneal_schedule': ['parameters'],
-             'annealing_time': ['parameters'],
-             'answer_mode': ['parameters'],
-             'auto_scale': ['parameters'],
-             # Snipped above response for brevity
-
-        See the :ref:`Ocean Glossary <index_concepts>` section
-        for explanations of technical terms in descriptions of Ocean tools.
+            >>> with DWaveSampler() as sampler:
+            ...     'auto_scale' in sampler.parameters
+            True
 
         """
         try:
@@ -304,18 +297,15 @@ def parameters(self):
 
     @property
     def edgelist(self):
-        """list: List of active couplers for the D-Wave solver.
+        """list: List of active couplers for the solver.
 
         Examples:
-            First 5 entries of the coupler list for one Advantage system.
+            First coupler for a selected Advantage2 system.
 
             >>> from dwave.system import DWaveSampler
-            >>> with DWaveSampler() as sampler:     # doctest: +SKIP
-            ...     sampler.edgelist[:5]
-            [(30, 31), (30, 45), (30, 2940), (30, 2955), (30, 2970)]
-
-        See the :ref:`index_concepts` section
-        for explanations of technical terms in descriptions of Ocean tools.
+            >>> with DWaveSampler(topology_type='zephyr') as sampler:
+            ...     sampler.edgelist[0]
+            (0, 1)
 
         """
         # Assumption: cloud client nodes are always integer-labelled
@@ -328,18 +318,15 @@ def edgelist(self):
 
     @property
     def nodelist(self):
-        """list: List of active qubits for the D-Wave solver.
+        """list: List of active qubits for the solver.
 
         Examples:
-            First 5 entries of the node list for one Advantage system.
+            First three qubits for a selected Advantage2 system.
 
             >>> from dwave.system import DWaveSampler
-            >>> with DWaveSampler() as sampler:     # doctest: +SKIP
-            ...     sampler.nodelist[:5]
-            [30, 31, 32, 33, 34]
-
-        See the :ref:`index_concepts` section
-        for explanations of technical terms in descriptions of Ocean tools.
+            >>> with DWaveSampler(topology_type='zephyr') as sampler:
+            ...     sampler.nodelist[:3]
+            [0, 1, 2]
 
         """
         # Assumption: cloud client nodes are always integer-labelled
@@ -381,11 +368,11 @@ def trigger_failover(self):
             pass
 
     def sample(self, bqm, warnings=None, **kwargs):
-        """Sample from the specified binary quadratic model.
+        """Sample from the specified :term:`binary quadratic model`.
 
         Args:
             bqm (:class:`~dimod.BinaryQuadraticModel`):
-                The binary quadratic model. Must match 
+                The binary quadratic model. Must match
                 :attr:`~DWaveSampler.nodelist` and :attr:`~DWaveSampler.edgelist`.
 
             warnings (:class:`~dwave.system.warnings.WarningAction`, optional):
@@ -394,15 +381,16 @@ def sample(self, bqm, warnings=None, **kwargs):
                 ignore warnings.
 
             **kwargs:
-                Optional keyword arguments for the sampling method, specified per solver in
-                :attr:`.parameters`. The :ref:`qpu_index_solver_properties` and
+                Optional keyword arguments for the sampling method, specified
+                per solver in :attr:`.parameters`. The
+                :ref:`qpu_index_solver_properties` and
                 :ref:`qpu_solver_parameters` sections describe the parameters
-                and properties supported on the D-Wave system.
+                and properties supported on D-Wave quantum computers.
 
         Returns:
-            :class:`~dimod.SampleSet`: Sample set constructed from a (non-blocking)
-            :class:`~concurrent.futures.Future`-like object.
-            In it this sampler also provides timing information in the `info`
+            :class:`~dimod.SampleSet`: Sample set constructed from a
+            (non-blocking) :class:`~concurrent.futures.Future`-like object.
+            In it this sampler also provides timing information in the ``info``
             field as described in the :ref:`qpu_sapi_qpu_timing` section.
 
         Examples:
