added some content, edits, and fixes for broken xrefs & todos

Author: JoelPasvolsky

docs/bibliography.rst

@@ -491,14 +491,12 @@ Bibliography
     M. W. Johnson et al. "Quantum annealing with manufactured spins."
     *Nature* 473 (May 12, 2011), pp. 194--198.
 
-.. todo:: find a place to reference this link, it's a nice one
 
-.. removed the section that used this but
 
-    .. [Jor2011]
-        Stephen Jordan.
-        "Quantum Algorithm Zoo."
-        https://math.nist.gov/quantum/zoo/
+.. [Jor2011]
+    Stephen Jordan.
+    "Quantum Algorithm Zoo."
+    https://quantumalgorithmzoo.org
 
 .. [Jue2016]
     Juexiao Su, Tianheng Tu, and Lei He.

docs/concepts/index.rst

@@ -361,24 +361,9 @@ Concepts and Terminology
         A state in which the values of variables violate a :term:`constraint`.
 
     Ising
-        Traditionally used in statistical mechanics. Variables are "spin up"
-        (:math:`\uparrow`) and "spin down" (:math:`\downarrow`), states that
-        correspond to :math:`+1` and :math:`-1` values. Relationships between
-        the spins, represented by couplings, are correlations or
-        anti-correlations. The :term:`objective function` expressed as an Ising
-        model is as follows:
-
-        .. math::
-            :nowrap:
-
-            \begin{equation}
-                \text{E}_{ising}(\pmb{s}) = \sum_{i=1}^N h_i s_i +
-                \sum_{i=1}^N \sum_{j=i+1}^N J_{i,j} s_i s_j
-            \end{equation}
-
-        where the linear coefficients corresponding to qubit biases
-        are :math:`h_i`, and the quadratic coefficients corresponding to
-        coupling strengths are :math:`J_{i,j}`.
+        .. include:: ../shared/models.rst
+            :start-after: start_models_ising_formula
+            :end-before: end_models_ising_formula
 
         Learn more:
 
@@ -560,43 +545,9 @@ Concepts and Terminology
         `Qubit on Wikipedia <https://en.wikipedia.org/wiki/Qubit>`_.
 
     QUBO
-        Quadratic unconstrained binary optimization.
-        QUBO problems are traditionally used in computer science. Variables
-        are TRUE and FALSE, states that correspond to 1 and 0 values.
-        A QUBO problem is defined using an upper-diagonal matrix :math:`Q`,
-        which is an :math:`N` x :math:`N` upper-triangular matrix of real
-        weights, and :math:`x`, a vector of binary variables, as minimizing the
-        function
-
-        .. math::
-            :nowrap:
-
-            \begin{equation}
-                f(x) = \sum_{i} {Q_{i,i}}{x_i} + \sum_{i<j} {Q_{i,j}}{x_i}{x_j}
-            \end{equation}
-
-        where the diagonal terms :math:`Q_{i,i}` are the linear coefficients and
-        the nonzero off-diagonal terms are the quadratic coefficients
-        :math:`Q_{i,j}`.
-        This can be expressed more concisely as
-
-        .. math::
-            :nowrap:
-
-            \begin{equation}
-                \min_{{x} \in {\{0,1\}^n}} {x}^{T} {Q}{x}.
-            \end{equation}
-
-        In scalar notation, the :term:`objective function` expressed as a QUBO
-        is as follows:
-
-        .. math::
-            :nowrap:
-
-            \begin{equation}
-                \text{E}_{qubo}(a_i, b_{i,j}; q_i) = \sum_{i} a_i q_i +
-                \sum_{i<j} b_{i,j} q_i q_j.
-            \end{equation}
+        .. include:: ../shared/models.rst
+            :start-after: start_models_qubo_formula
+            :end-before: end_models_qubo_formula
 
         See also `QUBO on Wikipedia <https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization>`_.
 

docs/concepts/models.rst

@@ -136,33 +136,18 @@ can represent both.
 Ising Model
 -----------
 
-The :term:`Ising` model is an :term:`objective function` of :math:`N` variables
-:math:`s=[s_1,...,s_N]` corresponding to physical Ising spins, where :math:`h_i`
-are the biases and :math:`J_{i,j}` the couplings (interactions) between spins.
-
-.. math::
-
-    \text{Ising:} \qquad
-    E(\bf{s})
-    = \sum_{i=1} h_i s_i +
-    \sum_{i<j} J_{i,j} s_i s_j
-    \qquad\qquad s_i\in\{-1,+1\}
+.. include:: ../shared/models.rst
+    :start-after: start_models_ising_formula
+    :end-before: end_models_ising_formula
 
 .. _concept_models_qubo:
 
 QUBO
 ----
 
-The :term:`QUBO` model is an objective function of :math:`N` binary variables
-represented as an upper-diagonal matrix :math:`Q`, where diagonal terms are the
-linear coefficients and the nonzero off-diagonal terms the quadratic
-coefficients.
-
-.. math::
-
-    \text{QUBO:} \qquad E(\bf{x})
-    =  \sum_{i\le j} x_i Q_{i,j} x_j
-    \qquad\qquad x_i\in \{0,1\}
+.. include:: ../shared/models.rst
+    :start-after: start_models_qubo_formula
+    :end-before: end_models_qubo_formula
 
 Other Models
 ============

docs/concepts/variables.rst

@@ -4,34 +4,34 @@
 Variables
 =========
 
-.. todo:: this section can do with some work, especially related to nonlinear
-    models
+This section mainly relates to the :term:`quadratic models <quadratic model>`
+submitted to |cloud|_ service solvers such as the :term:`hybrid` :term:`CQM`
+solver.\ [#]_ For the variables in :term:`nonlinear models <nonlinear model>`,
+see an introduction in the :ref:`opt_model_construction_nl` section and the
+reference documentation under the :ref:`index_optimization` section.
 
-|dwave_short|'s :term:`samplers <sampler>` mostly\ [#]_ solve
-:ref:`quadratic models <concept_models_quadratic>` of various sorts. Quadratic
-models are characterized by having one or two variables per term. A simple
-example of a quadratic model is,
-
-.. math::
-
-    D = Ax + By + Cxy
-
-where :math:`A`, :math:`B`, and :math:`C` are constants. Single variable
-terms---:math:`Ax` and :math:`By` here---are *linear* with the constant biasing
-the term's variable. Two-variable terms---:math:`Cxy` here---are *quadratic*
-with a relationship between the variables.
-
-The variables in these models may be of the following types.
+The variables in :ref:`supported models <concept_models>` may be of the
+following types.
 
 .. |variables_table| replace:: Supported Variables
 
 .. include:: ../shared/variables.rst
     :start-after: start_variables_table
     :end-before: end_variables_table
 
-.. [#] :ref:`Ocean <index_ocean_sdk>` software also provides some higher-order
-    tools for developing and testing your code; for example, the
-    :class:`~dimod.reference.samplers.ExactPolySolver` class.
+.. [#]
+
+    These models are characterized by having one or two variables per term. A simple
+    example of a quadratic model is,
+
+    .. math::
+
+        D = Ax + By + Cxy
+
+    where :math:`A`, :math:`B`, and :math:`C` are constants. Single variable
+    terms---:math:`Ax` and :math:`By` here---are *linear* with the constant biasing
+    the term's variable. Two-variable terms---:math:`Cxy` here---are *quadratic*
+    with a relationship between the variables.
 
 Variable Representations and Labels
 ===================================
@@ -81,3 +81,5 @@ Related Information
     nonlinear models.
 *   The :ref:`opt_model_construction_qm` section describes the construction of
     quadratic models.
+*   :ref:`quadratic models <concept_models_quadratic>` describes supported
+    models.

docs/industrial_optimization/developing_quantum_applications.rst

@@ -734,8 +734,7 @@ Your application will likely have multiple parts, including the following:
     it to a |dwave_short| solver for solution. It is recommended that you
     implement the :ref:`model <concept_models>` representing your
     problem, formulated as described in the previous section, and manage the
-    submission using the
-    `Ocean SDK <index_ocean_sdk>`.
+    submission using the :ref:`Ocean SDK <index_ocean_sdk>`.
 
 *   Handling inputs and presenting results
 

docs/industrial_optimization/dwave_hybrid.rst

@@ -188,8 +188,6 @@ branches.
 
     Racing Branches
 
-.. todo:: consider modifying this pulled-in example (markers will change)
-
 .. include:: ../ocean/api_ref_hybrid/README.rst
     :start-after: start_hybrid_example
     :end-before: end_hybrid_example

docs/leap_sapi/admin.rst

@@ -1535,6 +1535,9 @@ one of the following:
     *   -   **Completed**
         -   The solver has successfully completed its work on the problem.
 
+    *   -   **Cancelling**
+        -   A request to cancel work on a problem is being processed.
+
     *   -   **Cancelled**
         -   Work on the problem has been cancelled. Cancelled problems do not
             use any solver-access time.

docs/quantum_research/example_not.rst

@@ -150,7 +150,7 @@ unstructured problem (variables such as :math:`x_2` etc.) to the sampler's
 :ref:`graph structure <qpu_topologies>` (the QPU's numerically indexed qubits)
 in a process known as :term:`minor-embedding`.
 
-The next code sets up a D-Wave system as the sampler.
+The next code sets up a D-Wave quantum computer as the sampler.
 
 .. include:: ../shared/examples.rst
     :start-after: start_default_solver_config

docs/quantum_research/gate_model_intro.rst

@@ -18,4 +18,6 @@ Further Information
 ===================
 
 *   `Wikipedia's quantum circuit <https://en.wikipedia.org/wiki/Quantum_circuit>`_
-*   [Nel2010]_
+*   [Nel2010]_ is an introduction to the main ideas and techniques of the field
+    of quantum computation and quantum information.
+*   [Jor2011]_ is an online catalog of quantum algorithms.

docs/quantum_research/qubo_ising.rst

@@ -19,9 +19,6 @@ Finally, the :ref:`qpu_qubo_ising_example` subsection gives a simple example and
 the :ref:`qpu_qubo_ising_transformations` subsection shows how to convert
 between :term:`Ising` models and :term:`QUBOs <QUBO>`.
 
-.. todo:: consider consolidating and importing the ising & qubo definitions from
-    concepts/models
-
 .. _qpu_qubo_ising_bqm:
 
 Binary Quadratic Models
@@ -37,57 +34,18 @@ trivial, as shown in the :ref:`qpu_qubo_ising_transformations` section.
 Ising Model
 -----------
 
-The Ising model is traditionally used in statistical mechanics. Variables are
-"spin up" (:math:`\uparrow`) and "spin down" (:math:`\downarrow`), states that
-correspond to :math:`+1` and :math:`-1` values. Relationships between the spins,
-represented by couplings, are correlations or anti-correlations. The objective
-function expressed as an Ising model is as follows:
-
-.. math::
-
-    \text{E}_{ising}(\vc s) = \sum_{i=1}^N h_i s_i +
-    \sum_{i=1}^N \sum_{j=i+1}^N J_{i,j} s_i s_j
-
-where the linear coefficients corresponding to qubit biases are :math:`h_i`,
-and the quadratic coefficients corresponding to coupling strengths are
-:math:`J_{i,j}`.
+.. include:: ../shared/models.rst
+    :start-after: start_models_ising_formula
+    :end-before: end_models_ising_formula
 
 .. _qpu_qubo_ising_qubo:
 
 QUBO
 ----
 
-QUBO problems are traditionally used in computer science, with variables taking
-values 1 (TRUE) and 0 (FALSE).
-
-A QUBO problem is defined using an upper-diagonal matrix :math:`Q`, which is an
-:math:`N` x :math:`N` upper-triangular matrix of real weights, and :math:`x`, a
-vector of binary variables, as minimizing the function
-
-.. math::
-
-    f(x) = \sum_{i} {Q_{i,i}}{x_i} + \sum_{i<j} {Q_{i,j}}{x_i}{x_j}
-
-where the diagonal terms :math:`Q_{i,i}` are the linear coefficients and the
-nonzero off-diagonal terms  :math:`Q_{i,j}` are the quadratic coefficients.
-
-This can be expressed more concisely as
-
-.. math::
-
-    \min_{{x} \in {\{0,1\}^n}} {x}^{T} {Q}{x}.
-
-In scalar notation, the objective function expressed as a QUBO is as follows:
-
-.. math::
-
-    \text{E}_{qubo}(a_i, b_{i,j}; q_i) = \sum_{i} a_i q_i +
-    \sum_{i<j} b_{i,j} q_i q_j.
-
-.. note::
-    Quadratic unconstrained binary optimization problems---QUBOs---are
-    *unconstrained* in that there are no constraints on the variables other
-    than those expressed in *Q*.
+.. include:: ../shared/models.rst
+    :start-after: start_models_qubo_formula
+    :end-before: end_models_qubo_formula
 
 .. _qpu_qubo_ising_example:
 

docs/quantum_research/workflow.rst

@@ -90,6 +90,56 @@ Simple Sampling Example
 
 .. _qpu_workflow_simple_example:
 
-.. todo:: add example: Simple Workflow Example
-
-    Simple Workflow Example (title)
+Simple Workflow Example
+=======================
+
+This example uses the :ref:`Ocean software <index_ocean_sdk>` package,
+:ref:`index_dimod`, to formulate a small objective function: the
+:func:`~dimod.generators.combinations` function generates a :term:`BQM` that
+represents the problem of selecting exactly :math:`k` of :math:`n` binary
+variables.
+
+The following code creates a BQM that is minimized when exactly two
+(:math:`k=2`) of the three (:math:`n=3`) variables :code:`a, b, c` are
+:math:`1`:
+
+>>> import dimod
+>>> bqm = dimod.generators.combinations(['a', 'b', 'c'], 2)
+
+Now solve on a |dwave_short| quantum computer using the
+:class:`~dwave.system.samplers.DWaveSampler` sampler from Ocean software's
+:ref:`index_system` package. Also use its
+:class:`~dwave.system.composites.EmbeddingComposite` composite to map the
+unstructured problem (variables such as :math:`a` etc.) to the sampler's
+:ref:`graph structure <qpu_topologies>` (the QPU's numerically indexed qubits)
+in a process known as :term:`minor-embedding`.
+
+The next code sets up a D-Wave quantum computer as the sampler.
+
+.. include:: ../shared/examples.rst
+    :start-after: start_default_solver_config
+    :end-before: end_default_solver_config
+
+>>> from dwave.system import DWaveSampler, EmbeddingComposite
+>>> sampler = EmbeddingComposite(DWaveSampler())
+
+Because the sampled solution is probabilistic, returned solutions may differ
+between runs. Typically, when submitting a problem to the system, you ask for
+many samples, not just one. This way, you see multiple “best” answers and reduce
+the probability of settling on a suboptimal answer. Below, ask for 1000 samples.
+
+>>> sampleset = sampler.sample(bqm, num_reads=1000, label='SDK Examples - QPU Workflow')
+>>> print(sampleset)        # doctest: +SKIP
+   a  b  c energy num_oc. chain_.
+0  1  1  0    0.0     323     0.0
+1  1  0  1    0.0     339     0.0
+2  0  1  1    0.0     336     0.0
+3  1  1  1    1.0       1     0.0
+4  1  0  0    1.0       1     0.0
+['BINARY', 5 rows, 1000 samples, 3 variables]
+
+Almost all the returned samples represent valid value assignments for the
+:math:`\binom{N}{k}` problem, and minima (low-energy states) of the BQM, and
+with high likelihood the best (lowest-energy: here :math:`0.0` in the
+:code:`energy` column) samples satisfy the formulation (two :math:`1`\ s among
+the three variables columns, :code:`a, b, c`).