Merge pull request #146 from JoelPasvolsky/resources

Update resources (first pass)

docs/conf.py

@@ -30,7 +30,8 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
 ]
 
 # autodoc_default_flags = ['members']

docs/glossary.rst

@@ -11,8 +11,10 @@ Learn the relevant terminology at
 Index
 =====
 
-Terms defined in dimod:
+Terms defined in D-Wave Cloud Client:
 
+    * :term:`ising`
     * :term:`model`
+    * :term:`qubo`
     * :term:`sampler`
     * :term:`solver`

docs/reference/configuration.rst

@@ -10,7 +10,7 @@ Configuration
 Loading Configuration
 =====================
 
-These functions deploy D-Wave cloud client settings from a configuration file.
+These functions deploy D-Wave Cloud Client settings from a configuration file.
 
 .. currentmodule:: dwave.cloud.config
 

docs/reference/intro.rst

@@ -14,6 +14,8 @@ It's recommended you set up a configuration file through the interactive CLI uti
 Configuration Files
 -------------------
 
+** THE FOLLOWING IS JUST DRAFT CONTENT **
+
 Candidates paths for configuration files are set by the D-Wave homebase_ package.
 
 For example, on a Unix system, depending on its flavor, these might include (in order)::
@@ -35,6 +37,48 @@ For details on user/system config paths see homebase_.
 
 .. _homebase: https://github.com/dwavesystems/homebase
 
+
+One config file can contain multiple profiles, each defining a separate
+      (endpoint, token, solver, etc.) combination. Since config file conforms to a
+      standard Windows INI-style format, profiles are defined by sections like:
+      ``[profile-a]`` and ``[profile-b]``.
+
+      Default values for undefined profile keys are taken from the ``[defaults]``
+      section.
+
+      For example, assuming ``~/.config/dwave/dwave.conf`` contains::
+
+          [defaults]
+          endpoint = https://cloud.dwavesys.com/sapi
+          client = qpu
+
+          [dw2000]
+          solver = DW_2000Q_1
+          token = ...
+
+          [software]
+          client = sw
+          solver = c4-sw_sample
+          token = ...
+
+          [alpha]
+          endpoint = https://url.to.alpha/api
+          proxy = http://user:[email protected]:8080/
+          token = ...
+
+      We can instantiate a client for D-Wave 2000Q QPU endpoint with
+
+      >>> from dwave.cloud import Client
+      >>> client = Client.from_config(profile='dw2000')
+
+      and a client for remote software solver with::
+
+      >>> client = Client.from_config(profile='software')
+
+      ``alpha`` profile will connect to a pre-release API endpoint via defined HTTP
+      proxy server.
+
+
 Interactive CLI Configuration
 -----------------------------
 
@@ -57,10 +101,61 @@ Terminology
 
 .. glossary::
 
+    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 objective function expressed as an Ising model is as follows:
+
+         .. math::
+
+                  \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}`.
+
     model
         A collection of variables with associated linear and
         quadratic biases.
 
+    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::
+
+            \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::
+
+            \begin{equation}
+              \min_{{x} \in {\{0,1\}^n}} {x}^{T} {Q}{x}.
+            \end{equation}
+
+         In scalar notation, the objective function expressed as a QUBO
+         is as follows:
+
+         .. math::
+
+            \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}
+
     sampler
         A process that samples from low energy states of a problem’s objective function.
         A binary quadratic model (BQM) sampler samples from low energy states in models such

docs/reference/resources.rst

@@ -4,13 +4,29 @@
 Resources
 =========
 
-TODO: short description of term client
+The :term:`solver`\ s that provide sampling for solving :term:`Ising` and :term:`QUBO` problems, such
+as a D-Wave 2000Q QPU or a software :term:`sampler` such as the `dimod <https://github.com/dwavesystems/dimod>`_
+simulated annealing sampler, are typically remote resources. The D-Wave Cloud Client
+:class:`~dwave.cloud.client.Client` class manages such remote solver resources.
+
+Preferred use is with a context manager (a :code:`with Client.from_config(...) as`
+construct) to ensure proper closure of all resources. The following example snippet
+creates a client based on an auto-detected configuration file and instantiates
+a solver.
+
+>>> with Client.from_config() as client:   # doctest: +SKIP
+...     solver = client.get_solver('2000Q_ONLINE_SOLVER')
+
+Alternatively, the following example snippet creates a client for software resources
+that it later explicitly closes.
+
+>>> client = Client.from_config(client='sw')   # doctest: +SKIP
+>>> # code that uses client
+>>> client.close()    # doctest: +SKIP
 
 Base Client
 ===========
 
-.. currentmodule:: dwave.cloud
-
 .. automodule:: dwave.cloud.client
 
 Class
@@ -26,11 +42,11 @@ Methods
 .. autosummary::
    :toctree: generated
 
-   client.Client.close
    client.Client.from_config
    client.Client.get_solver
    client.Client.get_solvers
    client.Client.is_solver_handled
+   client.Client.close
 
 QPU Client
 ==========
@@ -59,7 +75,6 @@ Software-Samplers Client
 
 .. currentmodule:: dwave.cloud.sw
 
-.. automodule:: dwave.cloud.sw
 
 Class
 -----