Update descriptions and examples

CONTRIBUTING.rst

@@ -1,3 +1,4 @@
+.. _contributing:
 
 We, the qbsolv developers, expect a variety of contributions, from reporting of bugs or
 suggestions for examples or tutorials to development of improvements or alternatives to

README.rst

@@ -19,9 +19,10 @@ Qbsolv
 
 .. index-start-marker
 
-A decomposing solver that finds a minimum value of a large quadratic unconstrained binary optimization (QUBO)
-problem by splitting it into pieces. The pieces are solved using a classical solver running
-the tabu algorithm. qbsolv also enables configuring a D-Wave system as the solver.
+A decomposing solver that finds a minimum value of a large quadratic unconstrained binary
+optimization (QUBO) problem by splitting it into pieces. The pieces are solved using a
+classical solver running the tabu algorithm. qbsolv also enables configuring a D-Wave
+system as the solver.
 
 .. Note:: Access to a D-Wave system must be arranged separately.
 
@@ -35,14 +36,14 @@ Installation or Building
 Python
 ------
 
-A wheel might be available for your system on pypi. Source distributions are provided as well.
+A wheel might be available for your system on PyPI. Source distributions are provided as well.
 
 .. code-block:: python
 
     pip install dwave-qbsolv
 
 
-Alternately, you can build the library with setuptools
+Alternatively, you can build the library with setuptools.
 
 .. code-block:: bash
 
@@ -82,72 +83,64 @@ Description
 -----------
 
 qbsolv executes a quadratic unconstrained binary optimization
-(QUBO) problem represented in a file, providing bit-vector
-result(s) that minimizes (or optionally, maximizes) the value of
+(QUBO) problem represented in a file. It returns bit-vector
+results that minimizes---or optionally, maximizes---the value of
 the objective function represented by the QUBO.  The problem is
-represented in the QUBO(5) file format and notably is not limited
-to the size or connectivity pattern of the D-Wave system on which
-it will be executed.
+represented in QUBO(5) file format.
 
-The options are as follows:
+The QUBO input problem is not limited to the graph size or connectivity of a
+sampler, for example the D-Wave system.
+
+Options are as follows:
 
 .. code::
 
     -i infile
-        The name of the file in which the input QUBO resides.  This is a required
-        option.
+        Name of the file for the input QUBO. This option is mandatory.
     -o outfile
-        This optional argument denotes the name of the file to which the output
-        will be written.
-        The default is the standard output.
+        Optional output filename.
+        Default is the standard output.
     -a algorithm
-        This optional argument chooses nuances of the outer loop algorithm.  The
-        default is o.
+        Optional selection for the outer loop algorithm.  Default is o.
         'o' for original qbsolv method. Submatrix based upon change in energy.
         'p' for path relinking.  Submatrix based upon differences of solutions
     -m
-        This optional argument denotes to find the maximum instead of the minimum.
+        Optional selection of finding the maximum instead of the minimum.
     -T target
-        This optional argument denotes to stop execution when the target value of
-        the objective function is found.
+        Optional argument target value of the objective function. Stops execution when found.
     -t timeout
-        This optional argument stops execution when the elapsed cpu time equals or
-        exceeds timeout value. Timeout is only checked after completion of the main
-        loop. Other halt values such as 'target' and 'repeats' will halt before 'timeout'.
-        The default value is 2592000.0.
+        Optional timeout value. Stops execution when the elapsed CPU time equals or
+        exceeds it. Timeout is only checked after completion of the main
+        loop. Other halt values such as 'target' and 'repeats' halt before 'timeout'.
+        Default value is 2592000.0.
     -n repeats
-        This optional argument denotes, once a new optimal value is found, to repeat
-        the main loop of the algorithm this number of times with no change in optimal
-        value before stopping.
-        The default value is 50.
+        Optional number of times the main loop of the algorithm is repeated with
+        no change in optimal value found before stopping.
+        Default value is 50.
     -S subproblemSize
-        This optional argument indicates the size of the sub-problems into which
-        the QUBO will be decomposed.  A "-S 0" or "-S" argument not present indicates
-        to use the size specified in the embedding file found in the workspace set
-        up by DW.  If a DW environment has not been established, the value will
-        default to (47) and will use the tabu solver for subproblem solutions.
-        If a value is specified, qbsolv uses that value to create subproblem and
-        solve with the tabu solver.
+        Optional size of the sub-problems into which the QUBO is decomposed.
+        If no "-S 0" or "-S" argument is present, uses the size specified in the
+        embedding file found in the workspace set up by DW. If no DW environment is
+        established, value defaults to 47 and uses the tabu solver on subproblems.
+        If a value is specified, subproblems based on that size are solved with the
+        tabu solver.
     -w
-        If present, this optional argument will print the QUBO matrix and result
-        in .csv format.
+        If present, the QUBO matrix and result are printed in .csv format.
     -h
-        If present, this optional argument will print the help or usage message for
-        qbsolv and exit without execution.
+        If present, prints the help or usage message for qbsolv and exits without execution.
     -v verbosityLevel
-        This optional argument denotes the verbosity of output. A verbosityLevel of
-        0 (the default) will output the number of bits in the solution, the solution,
-        and the energy of the solution.  A verbosityLevel of 1 will output the same
-        information for multiple solutions, if found. A verbosityLevel of 2 will
-        also output more detailed information at each step of the algorithm. This
-        increases the output up to a value of 4.
+        Optional setting of the verbosity of output. The default verbosityLevel of
+        0 outputs the number of bits in the solution, the solution,
+        and the energy of the solution.  A verbosityLevel of 1 outputs the same
+        information for multiple solutions, if found. A verbosityLevel of 2
+        also outputs more detailed information at each step of the algorithm. The
+        information increases for verbosity levels of up to 4.
     -V
-        If present, this optional argument will emit the version number of the qbsolv
-        program and exit without execution.
+        If present, prints the version number of the qbsolv program and exits without execution.
     -q
-        If present, this optional argument triggers printing the format of the QUBO file.
+        If present, prints the format of the QUBO file.
     -r seed
-        Used to reset the seed for the random number generation
+        Used to reset the seed for the random number generation.
 
 .. usage-end-marker
 
@@ -156,57 +149,58 @@ qbsolv QUBO Input File Format
 
 .. format-start-marker
 
-A .qubo file contains data which describes an unconstrained
-quadratic binary optimization problem.  It is an ASCII file comprised
-of four types of lines:
+A .qubo file contains data that describes an unconstrained
+quadratic binary optimization problem.  It is an ASCII file comprising
+four types of lines:
 
-1. Comments - defined by a "c" in column 1.  They may appear
-   anywhere in the file, and are otherwise ignored.
+1. Comments defined by a "c" in column 1. Comments may appear
+   anywhere in the file, and are ignored.
 
-2. One program line, which starts with p in the first column.
-   The program line must be the first non-comment line in the file.
-   The program line has six required fields (separated by space(s)),
+2. Program line defined by a "p" in the first column.
+   A single program line must be the first non-comment line in the file.
+   The program line has six required fields separated by space(s),
    as in this example:
 
-.. code::
-
-   p   qubo  topology   maxNodes   nNodes   nCouplers
-
-where:
-
-.. code::
-
-   p          The problem line sentinel.
-   qubo       Identifies the file type.
-   topology   A string which identifies the topology of the problem and the specific
-              problem type.  For an unconstrained problem, target will be "0" or
-              "unconstrained."   Possible, for future implementations, valid strings
-              might include "chimera128" or "chimera512" (among others).
-   maxNodes   Number of nodes in the topology.
-   nNodes     Number of nodes in the problem (nNodes <= maxNodes).
-              Each node has a unique number and must take a value in the the range
-              {0 - (maxNodes-1)}.  A duplicate node number is an error.  The node
-              numbers need not be in order, and they need not be contiguous.
-   nCouplers  Number of couplers in the problem.  Each coupler is a unique connection
-              between two different nodes.  The maximum number of couplers is (nNodes)^2.
-              A duplicate coupler is an error.
-
-3. nNodes clauses.  Each clause is made up of three numbers.  The numbers are separated
-   by one or more blanks.  The first two numbers must be integers and are the number
-   for this node (repeated).  The node number must be in {0 , (maxNodes-1)}. The third
-   value is the weight associated with the node, may be an integer or float, and can
-   take on any positive or negative value, or zero.
-
-4. nCouplers clauses.  Each clause is made up of three numbers.  The numbers are
-   separated by one or more blanks.  The first two numbers must be different integers
-   and are the node numbers for this coupler.  The two values (i and j) must have (i < j).
-   Each number must be one of the nNodes valid node numbers (and thus in {0, (maxNodes-1)}).
-   The third value is the strength associated with the coupler, may be an integer or float,
-   and can take on any positive or negative value, but not zero.  Every node must connect
-   with at least one other node (thus must have at least one coupler connected to it).
+    .. code::
+
+       p   qubo  topology   maxNodes   nNodes   nCouplers
+
+    where:
+
+    .. code::
+
+       p          Problem line sentinel.
+       qubo       File type identifier.
+       topology   String that identifies the topology of the problem and the specific
+                  problem type. For an unconstrained problem, target is "0" or
+                  "unconstrained." In future implementations, valid strings
+                  might include "chimera128" or "chimera512" (among others).
+       maxNodes   Number of nodes in the topology.
+       nNodes     Number of nodes in the problem (nNodes <= maxNodes).
+                  Each node has a unique number and must take a value in the range
+                  {0 - (maxNodes-1)}. A duplicate node number is an error. Node
+                  numbers need not be in order, and need not be contiguous.
+       nCouplers  Number of couplers in the problem. Each coupler is a unique connection
+                  between two different nodes. The maximum number of couplers is (nNodes)^2.
+                  A duplicate coupler is an error.
+
+3. nNodes clauses. Each clause is made up of three numbers, separated
+   by one or more blanks. The first two numbers must be integers and are the number
+   for this node (repeated). The node number must be in range {0 , (maxNodes-1)}.
+   The third value is the weight associated with the node. Weight may be an integer
+   or float, and can take on any positive or negative value, or be set to zero.
+
+4. nCouplers clauses. Each clause is made up of three numbers, separated by one or
+   more blanks. The first two numbers, (i and j), are the node numbers for this coupler
+   and must be different integers, where (i < j).Each number must be one of the nNodes
+   valid node numbers (and thus in range {0, (maxNodes-1)}).
+   The third value is the strength associated with the coupler. Strength may be an
+   integer or float, and can take on any positive or negative value, but not zero.
+   Every node must connect with at least one other node (thus must have at least
+   one coupler connected to it).
 
 Here is a simple QUBO file example for an unconstrained QUBO with 4
-nodes and 6 couplers.  This example is provided to illustrate the
+nodes and 6 couplers. This example is provided to illustrate the
 elements of a QUBO benchmark file, not to represent a real problem.
 
 .. code::

docs/intro.rst

@@ -2,4 +2,44 @@
 Introduction
 ============
 
-See :download:`Partitioning Optimization Problems for Hybrid Classical/Quantum Execution <../qbsolv_techReport.pdf>` for a description of the algorithm and implementation.
+Divide-and-conquer and dynamic programming algorithms have a rich history in computer
+science for problems with large numbers of variables. Many hard problems that can benefit
+from quantum computers are to large to map directly to a QPU. To solve a problem with
+more variables than the available number of qubits, we break the problem into subproblems, solve the
+subproblems, and then reconstruct an answer to the original problem from the subproblem
+solutions.
+
+qbsolv is one such decomposing solver. It provides two interfaces:
+
+* :ref:`usage` (CLI)
+
+  The tabu algorithm is executed on the problem which is divided into subproblems of
+  several dozen variables each.
+* :ref:`python`
+
+  The Python interface provides a :class:`~dwave_qbsolv.QBSolv` class wrapper for
+  the qbsolv C code. A `dimod` sampler can be substituted for the default tabu algorithm.
+
+For a description of the algorithm and implementation, see
+:download:`Partitioning Optimization Problems for Hybrid Classical/Quantum Execution <../qbsolv_techReport.pdf>`.
+
+For a description of the tabu search algorithm, see `Tabu search <https://en.wikipedia.org/wiki/Tabu_search>`_\ .
+
+Example
+=======
+
+This example sends 30-variable sub-problems of a 500-variable QUBO to the `dwave-neal`
+sampler to be incorporated into the tabu results run in the main loop of qbsolv. 
+
+>>> from dwave_qbsolv import QBSolv
+>>> import neal
+>>> import itertools
+>>> import random
+...
+>>> qubo_size = 500
+>>> subqubo_size = 30
+>>> Q = {t: random.uniform(-1, 1) for t in itertools.product(range(qubo_size), repeat=2)}
+>>> sampler = neal.SimulatedAnnealingSampler()
+>>> response = QBSolv().sample_qubo(Q, solver=sampler, solver_limit=subqubo_size)
+>>> print("energies=" + str(list(response.data_vectors['energy'])))   # doctest: +SKIP
+energies=[-2800.794817495185]

docs/source/index.rst

@@ -6,5 +6,5 @@ Reference Documentation
   :maxdepth: 1
 
   usage
-  format
   python
+  format

docs/source/python.rst

@@ -1,8 +1,8 @@
 .. _python:
 
-======
-Python
-======
+================
+Python Interface
+================
 
 .. automodule:: dwave_qbsolv
 

docs/source/usage.rst

@@ -1,6 +1,10 @@
-============
-Using qbsolv
-============
+.. _usage:
+
+======================
+Command Line Interface
+======================
+
+Use the following command with its options to run qbsolv from a terminal.
 
 .. include::  ../../README.rst
   :start-after: usage-start-marker